From 48c2c7fd8349439d67582742794bd75da0765ec3 Mon Sep 17 00:00:00 2001 From: Dale Henrichs Date: Wed, 1 Oct 2014 10:21:42 -0700 Subject: [PATCH] Issue #241: checkpoint in user guide docs and tests --- .travis.yml | 4 +- docs/MetacelloUserGuide.md | 53 ++++++++++----------- tests/userGuide.st | 98 +++++++++++++++++++++++++++----------- 3 files changed, 95 insertions(+), 60 deletions(-) diff --git a/.travis.yml b/.travis.yml index 530c31f05..85a4c080b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -24,8 +24,8 @@ env: # - ST=Pharo-2.0 LoadList="'TravisCI_1' 'TravisCI_2'" TRAVIS_SCRIPT=travisCI.st # - ST=Pharo-2.0 LoadList="'TravisCI_3'" TRAVIS_SCRIPT=travisCI.st - - ST=GemStone-3.2.2 LoadList="'TravisCI_1' 'TravisCI_2'" TRAVIS_SCRIPT=travisCI.st - - ST=GemStone-3.2.2 LoadList="'TravisCI_3'" TRAVIS_SCRIPT=travisCI.st +# - ST=GemStone-3.2.2 LoadList="'TravisCI_1' 'TravisCI_2'" TRAVIS_SCRIPT=travisCI.st +# - ST=GemStone-3.2.2 LoadList="'TravisCI_3'" TRAVIS_SCRIPT=travisCI.st # - ST=Squeak-4.5 LoadList="'TravisCI_1' 'TravisCI_2'" TRAVIS_SCRIPT=travisCI.st # - ST=Squeak-4.5 LoadList="'TravisCI_3'" TRAVIS_SCRIPT=travisCI.st # until Issue # diff --git a/docs/MetacelloUserGuide.md b/docs/MetacelloUserGuide.md index b7aeb666c..2cc818d5e 100644 --- a/docs/MetacelloUserGuide.md +++ b/docs/MetacelloUserGuide.md @@ -70,8 +70,6 @@ Metacello new load. ``` -#PROGRESS MARKER - ##Listing Once you've loaded one or more projects into your image, you may want to @@ -97,7 +95,7 @@ specifying the names of the projects you'd like to select: ```Smalltalk Metacello registry - configuration: #('Seaside30' 'MetacelloPreview'); + configuration: #('Seaside3' 'MetacelloPreview'); list. ``` @@ -126,7 +124,7 @@ with `Seaside` in the Once you've loaded a project into your image the next logical step is upgrading your project to a new version. -Let's say that a new `#stable` version of Seaside30 has been released +Let's say that a new `#stable` version of Seaside3 has been released and that you want to upgrade. This is a two step process: * [get a new version of the configuration][11] @@ -147,7 +145,7 @@ By using the `image` message, you can leverage the fact that the [registry][8] r from which repository you loaded the original version of the configuration. The `get` command simply downloads the latest version of the -configuration package from the repository. +configuration package from that repository. You may download the configuration from a different repository: @@ -166,12 +164,12 @@ into your image without actually loading the project itself: ```Smalltalk Metacello image - configuration: 'SeasideRest'; - repository: 'http://smalltalkhub.com/mc/Seaside/MetacelloConfigurations/main'; + configuration: 'Magritte3'; + repository: 'http://smalltalkhub.com/mc/Magritte/Magritte3/main'; get. ``` -The 'SeasideRest' project information will be registered in the [registry][8] and marked +The 'Magritte3' project information will be registered in the [registry][8] and marked as *unloaded*. ### Load the new version @@ -194,11 +192,11 @@ command operation. Of course, the `load` command updates the [registry][8]. If you want to load a project for which you've already done a `get` -(like the SeasideRest project earlier), you can do the following: +(like the Magritte project earlier), you can do the following: ```Smalltalk Metacello registry - configuration: 'SeasideRest'; + configuration: 'Magritte'; version: #stable; load. ``` @@ -208,21 +206,21 @@ interested in both *loaded* and *unloaded* projects. ##Locking -Let's say that you are using an older version of Seaside30 (say 3.0.5) -instead of the #stable version (3.0.7) and that your application doesn't -work with newer versions of Seaside30 (you've tried and it's more work -to get you application to work with the newer version of Seaside30 than +Let's say that you are using an older version of Seaside3 (say 3.1.1) +instead of the #stable version (3.1.3) and that your application doesn't +work with newer versions of Seaside3 (you've tried and it's more work +to get you application to work with the newer version of Seaside3 than it's worth). Let's also say that you want to try out something in the -SeasideRest project, but when you try loading SeasideRest, you end up -having Seaside 3.0.7 loaded as well. +Magritte project, but when you try loading Magritte, you end up +having Seaside 3.1.3 loaded as well. This is an unfortunate side effect of Metacello trying to *do the right thing*, only in your case it is the wrong thing. Fortunately, the [`lock` command][9] can give you control. First you -need to `lock` the Seaside30 project: +need to `lock` the Seaside3 project: ```Smalltalk Metacello image @@ -256,8 +254,7 @@ you can use `onWarning:` to log and resume the Warning: ```Smalltalk Metacello registry - configuration: 'SeasideRest'; - version: #stable; + configuration: 'Magritte3'; onWarning: [:ex | Transcript cr; show: 'Warning: ', ex description. ex resume ]; @@ -269,29 +266,27 @@ which is only triggered when a locked project is involved: ```Smalltalk Metacello registry - configuration: 'SeasideRest'; - version: #stable; + configuration: 'Magritte3'; onLock: [:ex :existing :new | Transcript cr; show: 'Locked project: ', existing projectName printString. - ex pass ]; + ex honor]; load. ``` -### Bypassing locks +### Breaking locks -Let's say that when you load the SeasideRest project you have decided +Let's say that when you load the Magritte3 project you have decided that in this particular case you would like to bypass the lock and let -the version of Seaside specified by the SeasideRest project to be loaded. +the version of Seaside specified by the Magritte3 project to be loaded. -We'll use `onLock:` to `break` the new version of the Seaside project to +We'll use `onLock:` to `break` the lock and allow the new version of the Seaside project to be loaded: ```Smalltalk Metacello registry - configuration: 'SeasideRest'; - version: #stable; + configuration: 'Magritte3'; onLock: [:ex :existing :new | - existing baseName = 'Seaside31' + existing baseName = 'Seaside3' ifTrue: [ ex break ]. ex pass ]; load. diff --git a/tests/userGuide.st b/tests/userGuide.st index c6a630c97..9854a664a 100644 --- a/tests/userGuide.st +++ b/tests/userGuide.st @@ -79,40 +79,30 @@ Smalltalk at: #ConfigurationOfGLASS ifPresent: [:ignored | "Run smattering of expressions used in Metacello User Guide ... not all expressions are implemented yet... We just want these expressions to run without error" - +[ Transcript cr; show: '---Start running documentation script..'. +"Loading" Transcript cr; show: '---get (default)'. Metacello new configuration: 'Seaside3'; get. Transcript cr; show: '---load (default)'. -[ Metacello new configuration: 'Seaside3'; - load ] - on: Warning - do: [:ex | - Transcript cr; show: ex description. - ex resume ]. - -Transcript cr; show: '---get'. -Metacello new - configuration: 'Seaside3'; - smalltalkhubUser: 'Seaside' project: 'MetacelloConfigurations'; - get. + load. Transcript cr; show: '---load'. Metacello registry configuration: 'Seaside3'; version: #stable; - onWarning: [:ex | - Transcript cr; show: 'WARNING: ', ex description. - ex resume]; - onUpgrade: [:ex | ex allow ]; + onConflict: [:ex | ex allow ]; + smalltalkhubUser: 'Seaside' project: 'MetacelloConfigurations'; + get; load. +"Listing" Transcript cr; show: '---list (1)'. Metacello image configuration: [:spec | true ]; @@ -128,6 +118,7 @@ Metacello new smalltalkhubUser: 'Seaside' project: 'Seaside31'; list. +"Getting" Transcript cr; show: '---get (image)'. Metacello image configuration: 'Seaside3'; @@ -139,10 +130,33 @@ Metacello image smalltalkhubUser: 'Seaside' project: 'MetacelloConfigurations'; get. +Transcript cr; show: '---get (Magritte3)'. +Metacello image + configuration: 'Magritte3'; + repository: 'http://smalltalkhub.com/mc/Magritte/Magritte3/main'; + get. + +"Load the new version" +Transcript cr; show: '---load (Seaside3)'. +Metacello image + configuration: 'Seaside3'; + version: #stable; + load. + +Transcript cr; show: '---load (Magritte3)'. +Metacello image + configuration: 'Seaside3'; + lock. "lock to preserve currently loaded Seaside..." + +Metacello registry + configuration: 'Magritte'; + version: #stable; + load. + +"Locking" Transcript cr; show: '---lock'. Metacello image configuration: 'Seaside3'; - version: #'stable'; lock. Transcript cr; show: '---lock (3.1.2)'. @@ -151,19 +165,45 @@ Metacello image version: '3.1.2'; lock. -Transcript cr; show: '---load (Zinc)'. -Metacello new - baseline: 'Zinc'; - repository: 'github://glassdb/zinc:gemstone3.1/repository'; - get; - load: 'Tests'. +Transcript cr; show: '---lock warning'. +Metacello registry + configuration: 'Magritte3'; + onWarning: [:ex | + Transcript cr; show: 'Warning: ', ex description. + ex resume ]; + load. -Transcript cr; show: '---load (Zinc onConflict)'. +Transcript cr; show: '---lock tracking'. Metacello registry - baseline: 'Zinc'; - onConflict: [:ex | ex useNew ]; - get; - load: 'Tests'. + configuration: 'Magritte3'; + onLock: [:ex :existing :new | + Transcript cr; show: 'Locked project: ', existing projectName printString. + ex pass ]; + load. + +Transcript cr; show: '---lock breaking'. +Metacello registry + configuration: 'Magritte3'; + onLock: [:ex :existing :new | + existing baseName = 'Seaside3' + ifTrue: [ ex break ]. + ex pass ]; + load. + +"upgrading a locked project" +Transcript cr; show: '---lock upgrading'. +Metacello image + configuration: 'Seaside3'; + version: '3.1.2'; + lock. + +"locking example" + +] + on: Warning + do: [:ex | + Transcript cr; show: ex description. + ex resume ] TravisCISuccessNoFailure value: 'TravisCISuccess.txt'.