Updated instructions for trunk updating configurations

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
6 messages Options
cbc
Reply | Threaded
Open this post in threaded view
|

Updated instructions for trunk updating configurations

cbc
Based on feedback from last round of asking for feedback (and a few spelling fixes, too).  I have removed discussion about the method movement, since it *should* just work; and I've put pointers in for new topic on renaming classes.

Plus, we'll need to document what is happening in Congifurations and Monticello, maybe, to make it more reasonable to use these.

-----
When and How to change the trunk update configuration:
* First, only create a configuration when it is necessary.  Extra configurations slow down the update process.  BUT, missing a config that should be there BREAKS the update process.  Ask when not sure
* When you are adding a new package to trunk, update the configuration with the new package (just because a package is in the repository does not mean it is loaded)
* When you are removing a package from trunk, update the configuration to remove the package (and follow instructions for removing the package)
* When you need to ensure a preamble or postscript script is run for a package, include the version in a new configuration (otherwise it could be skipped - trunk only loads the latest version of a package if specific versions are not called out in the update configuration)
* When you are renaming a class (follow the instructions for class renaming in trunk)
* If you need to do very intricate, step by step surgery on the internals of Squeak itself, such as converting how contexts work, you should use a series of update configurations to ensure step by step applications of the packages so the trunk update is successful
* When you are unsure - ask.  If no response in a reasonable time (day(s), or sooner if it is to patch a broken trunk process, to wait for a response), then go ahead a build a config.

To update the configuration:
1. Update from trunk to the latest
2. Open the trunk package
3. Select the 'update' package, find the last update commit, and "Browse" it (with the button)
4. In the MCConfigurationBrowser, press the "Update" button and choose "update all from image"
5. If you need to add a new package, press the "Add" button and chose the package to add (it needs to be in your image with the right version to add it)
6. If you need to remove a package, select the package and press "Remove"
7. If you packages are updating that have dependencies between each other (say, adding an abstract class to one package, and a subclass of that abstract class in another package), then you will need to make sure those packages are in the right order.  In this case, find the package with the subclass, and make sure it is after the abstract classes package.  Do this by selecting one package and pressing the "Up" and "Down" keys until the packages are in the right order
8. Finally, save the package back to Trunk, and test out the update stream to ensure it works.
-----

Thanks,
cbc



Reply | Threaded
Open this post in threaded view
|

Re: Updated instructions for trunk updating configurations

Bert Freudenberg
On 18 February 2018 at 23:30, Chris Cunningham <[hidden email]> wrote:
Based on feedback from last round of asking for feedback (and a few spelling fixes, too).  I have removed discussion about the method movement, since it *should* just work; and I've put pointers in for new topic on renaming classes.

Plus, we'll need to document what is happening in Congifurations and Monticello, maybe, to make it more reasonable to use these.

-----
When and How to change the trunk update configuration:
* First, only create a configuration when it is necessary.  Extra configurations slow down the update process.  BUT, missing a config that should be there BREAKS the update process.  Ask when not sure
* When you are adding a new package to trunk, update the configuration with the new package (just because a package is in the repository does not mean it is loaded)
* When you are removing a package from trunk, update the configuration to remove the package (and follow instructions for removing the package)
* When you need to ensure a preamble or postscript script is run for a package, include the version in a new configuration (otherwise it could be skipped - trunk only loads the latest version of a package if specific versions are not called out in the update configuration)

​Not quite. If you need a preamble/postscript to run again, it needs to be modified (just add a new line or space). 

These scripts should be coded to be safely run multiple times. That means, each part of the script should check if it is necessary to run, then execute the needed system massaging. Newer additions should go on the bottom. It's not usually needed to remove older parts of the script when they are properly protected by these guards. But after some time passes (let's say after a new system release) then cleaning up these scripts is a good idea.

A modified script *​will* be run at the next update even if not mentioned explicitly in a config map. That is because as the last step of updating, the updater builds an implicit config map from all the latest packages in the default repository, and loads it.
 
* When you are renaming a class (follow the instructions for class renaming in trunk)
* If you need to do very intricate, step by step surgery on the internals of Squeak itself, such as converting how contexts work, you should use a series of update configurations to ensure step by step applications of the packages so the trunk update is successful
* When you are unsure - ask.  If no response in a reasonable time (day(s), or sooner if it is to patch a broken trunk process, to wait for a response), then go ahead a build a config.

To update the configuration:
1. Update from trunk to the latest
2. Open the trunk package
3. Select the 'update' package, find the last update commit, and "Browse" it (with the button)
4. In the MCConfigurationBrowser, press the "Update" button and choose "update all from image"
5. If you need to add a new package, press the "Add" button and chose the package to add (it needs to be in your image with the right version to add it)
6. If you need to remove a package, select the package and press "Remove"
7. If you packages are updating that have dependencies between each other (say, adding an abstract class to one package, and a subclass of that abstract class in another package), then you will need to make sure those packages are in the right order.  In this case, find the package with the subclass, and make sure it is after the abstract classes package.  Do this by selecting one package and pressing the "Up" and "Down" keys until the packages are in the right order
8. Finally, save the package back to Trunk, and test out the update stream to ensure it works.
-----

Thanks,
cbc


​Rest looks good to me, but I didn't double-check if we mentioned anything else in the discussion.

- Bert -​



bpi
Reply | Threaded
Open this post in threaded view
|

Re: Updated instructions for trunk updating configurations

bpi
What would it take to make it possible to test the update process beforehand, if possible locally? I guess a lot less fixing of the update stream would be necessary this way. It might also remove the barrier for less experienced people to contribute.

Thanks for all your contributions!

Bernhard

> Am 19.02.2018 um 17:34 schrieb Bert Freudenberg <[hidden email]>:
>
> On 18 February 2018 at 23:30, Chris Cunningham <[hidden email]> wrote:
> Based on feedback from last round of asking for feedback (and a few spelling fixes, too).  I have removed discussion about the method movement, since it *should* just work; and I've put pointers in for new topic on renaming classes.
>
> Plus, we'll need to document what is happening in Congifurations and Monticello, maybe, to make it more reasonable to use these.
>
> -----
> When and How to change the trunk update configuration:
> * First, only create a configuration when it is necessary.  Extra configurations slow down the update process.  BUT, missing a config that should be there BREAKS the update process.  Ask when not sure
> * When you are adding a new package to trunk, update the configuration with the new package (just because a package is in the repository does not mean it is loaded)
> * When you are removing a package from trunk, update the configuration to remove the package (and follow instructions for removing the package)
> * When you need to ensure a preamble or postscript script is run for a package, include the version in a new configuration (otherwise it could be skipped - trunk only loads the latest version of a package if specific versions are not called out in the update configuration)
>
> ​Not quite. If you need a preamble/postscript to run again, it needs to be modified (just add a new line or space).
>
> These scripts should be coded to be safely run multiple times. That means, each part of the script should check if it is necessary to run, then execute the needed system massaging. Newer additions should go on the bottom. It's not usually needed to remove older parts of the script when they are properly protected by these guards. But after some time passes (let's say after a new system release) then cleaning up these scripts is a good idea.
>
> A modified script *​will* be run at the next update even if not mentioned explicitly in a config map. That is because as the last step of updating, the updater builds an implicit config map from all the latest packages in the default repository, and loads it.
>  
> * When you are renaming a class (follow the instructions for class renaming in trunk)
> * If you need to do very intricate, step by step surgery on the internals of Squeak itself, such as converting how contexts work, you should use a series of update configurations to ensure step by step applications of the packages so the trunk update is successful
> * When you are unsure - ask.  If no response in a reasonable time (day(s), or sooner if it is to patch a broken trunk process, to wait for a response), then go ahead a build a config.
>
> To update the configuration:
> 1. Update from trunk to the latest
> 2. Open the trunk package
> 3. Select the 'update' package, find the last update commit, and "Browse" it (with the button)
> 4. In the MCConfigurationBrowser, press the "Update" button and choose "update all from image"
> 5. If you need to add a new package, press the "Add" button and chose the package to add (it needs to be in your image with the right version to add it)
> 6. If you need to remove a package, select the package and press "Remove"
> 7. If you packages are updating that have dependencies between each other (say, adding an abstract class to one package, and a subclass of that abstract class in another package), then you will need to make sure those packages are in the right order.  In this case, find the package with the subclass, and make sure it is after the abstract classes package.  Do this by selecting one package and pressing the "Up" and "Down" keys until the packages are in the right order
> 8. Finally, save the package back to Trunk, and test out the update stream to ensure it works.
> -----
>
> Thanks,
> cbc
>
>
> ​Rest looks good to me, but I didn't double-check if we mentioned anything else in the discussion.
>
> - Bert -​


cbc
Reply | Threaded
Open this post in threaded view
|

Re: Updated instructions for trunk updating configurations

cbc
In reply to this post by Bert Freudenberg


On Mon, Feb 19, 2018 at 8:34 AM, Bert Freudenberg <[hidden email]> wrote:
On 18 February 2018 at 23:30, Chris Cunningham <[hidden email]> wrote:
Based on feedback from last round of asking for feedback (and a few spelling fixes, too).  I have removed discussion about the method movement, since it *should* just work; and I've put pointers in for new topic on renaming classes.
... 
* When you need to ensure a preamble or postscript script is run for a package, include the version in a new configuration (otherwise it could be skipped - trunk only loads the latest version of a package if specific versions are not called out in the update configuration)

​Not quite. If you need a preamble/postscript to run again, it needs to be modified (just add a new line or space). 

These scripts should be coded to be safely run multiple times. That means, each part of the script should check if it is necessary to run, then execute the needed system massaging. Newer additions should go on the bottom. It's not usually needed to remove older parts of the script when they are properly protected by these guards. But after some time passes (let's say after a new system release) then cleaning up these scripts is a good idea.

A modified script *​will* be run at the next update even if not mentioned explicitly in a config map. That is because as the last step of updating, the updater builds an implicit config map from all the latest packages in the default repository, and loads it.

I didn't get across what I wanted here.  The idea/concern was that if the script was added since the last update configuration, and is being changed again without the package being mentioned in the next update configuration, then one of the previous versions with the previous script needs to be specifically mentioned in an update configuration.  Otherwise folks updating from an older version of the image will skip all versions of the package with the older script.

Of course, that isn't even close to what I wrote, was it?

So, how about that mention of the scripts be removed from here.  Somehow the usage (what you said above) is added to the script editor for clarity of the user (and maybe documented in the Wiki for good measure as well).  And the release instructions mentions building a specific config map for the release (?) that ensures all past scripts have been run, so it is safe to clear them out if desired.

-cbc


cbc
Reply | Threaded
Open this post in threaded view
|

Re: Updated instructions for trunk updating configurations

cbc
In reply to this post by bpi


On Wed, Feb 21, 2018 at 9:46 AM, Bernhard Pieber <[hidden email]> wrote:
What would it take to make it possible to test the update process beforehand, if possible locally? I guess a lot less fixing of the update stream would be necessary this way. It might also remove the barrier for less experienced people to contribute.

Thanks for all your contributions!

Bernhard

That might be a reasonable idea.

There was a discussion not long ago about hosting running a source.squeak.org copy on our local laptops - if that was running AND we had the packages copied locally, this testing the update process locally could work, I would think.

-cbc


Reply | Threaded
Open this post in threaded view
|

Re: Updated instructions for trunk updating configurations

Levente Uzonyi
In reply to this post by cbc
On Sun, 4 Mar 2018, Chris Cunningham wrote:

>
>
> On Mon, Feb 19, 2018 at 8:34 AM, Bert Freudenberg <[hidden email]> wrote:
>       On 18 February 2018 at 23:30, Chris Cunningham <[hidden email]> wrote:
>       Based on feedback from last round of asking for feedback (and a few spelling fixes, too).  I have removed discussion about the
>       method movement, since it *should* just work; and I've put pointers in for new topic on renaming classes.
>
> ... 
>             * When you need to ensure a preamble or postscript script is run for a package, include the version in a new configuration
>             (otherwise it could be skipped - trunk only loads the latest version of a package if specific versions are not called out
>             in the update configuration)
>
>
> ​Not quite. If you need a preamble/postscript to run again, it needs to be modified (just add a new line or space). 
>
> These scripts should be coded to be safely run multiple times. That means, each part of the script should check if it is necessary to run,
That would only be possible if you were able to predict the future. The
condition the script checks may become true again later.

> then execute the needed system massaging. Newer additions should go on the bottom. It's not usually needed to remove older parts of the
> script when they are properly protected by these guards. But after some time passes (let's say after a new system release) then cleaning up
> these scripts is a good idea.

I wrote several of these scripts in the past, and based on my experience,
I think it's perfectly fine not to make them runnable multiple times, and
it's also perfectly fine to delete those which have been executed.
This is because of the nature of these scripts, you only want to run them
once. If you want to run something multiple times, you'll create a method
instead of using these scripts.

>
> A modified script *​will* be run at the next update even if not mentioned explicitly in a config map. That is because as the last step of
> updating, the updater builds an implicit config map from all the latest packages in the default repository, and loads it.
>
> I didn't get across what I wanted here.  The idea/concern was that if the script was added since the last update configuration, and is being
> changed again without the package being mentioned in the next update configuration, then one of the previous versions with the previous script
> needs to be specifically mentioned in an update configuration.  Otherwise folks updating from an older version of the image will skip all versions

These scripts must work the first time, you simply don't change them
again.
If you have to change them, then the update stream is already in a broken
state. Fixing it from that point will involve things you wouldn't do
normally: delete/reupload the package/config map, etc.

How to check if the scripts work?
0. prepare your package versions
1. get a fresh image
2. load them one-by-one in the order the update process would
3. back to 0 if there's an error

This of course won't work if you want to change the update process itself,
which is close to impossible right now. I think forking a process to load
each .mcm would help with that.

Sometimes it's worth to think about external packages too: just because
something won't affect a pure Trunk image, it may cause problems if there
are other packages loaded into your image.

Levente

> of the package with the older script.
>
> Of course, that isn't even close to what I wrote, was it?
>
> So, how about that mention of the scripts be removed from here.  Somehow the usage (what you said above) is added to the script editor for clarity
> of the user (and maybe documented in the Wiki for good measure as well).  And the release instructions mentions building a specific config map for
> the release (?) that ensures all past scripts have been run, so it is safe to clear them out if desired.
>
> -cbc
>
>