Skip to content

Commit

Permalink
Issue #241: remove Lock Example section of user guide in favor of ful…
Browse files Browse the repository at this point in the history
…l lock example document ... fix typo in user guide tests
  • Loading branch information
dalehenrich committed Oct 1, 2014
1 parent 48c2c7f commit 6b9134c
Show file tree
Hide file tree
Showing 2 changed files with 1 addition and 139 deletions.
138 changes: 0 additions & 138 deletions docs/MetacelloUserGuide.md
Original file line number Diff line number Diff line change
Expand Up @@ -311,144 +311,6 @@ Metacello image

The newly loaded of the project will continue to be locked.

### Locking Example

A [detailed locking example project](LockCommandReference.md) is available.

## Switching Project Repositories

If you have loaded a project directly from GitHub, say
the Zinc repository:

```Smalltalk
Metacello new
baseline: 'Zinc';
repository: 'github://glassdb/zinc:gemstone3.1/repository';
get;
load: 'Tests'
```

The ``github://` repository is read only. If you want to save new versions
of packages to the repository, you must clone the GitHub repository to your
local disk:

```Shell
cd /opt/git
git clone https://github.com/glassdb/zinc.git
cd zinc
git checkout gemstone3.1
```

Then load Zinc from the local git repository using a
`filetree://` repository:

```Smalltalk
Metacello new
baseline: 'Zinc';
repository: 'filetree:///opt/git/zinc/repository';
onConflict: [:ex | ex useNew ];
get;
load: 'Tests'
```

Note that we are using an `onConflict:` block.

Metacello recognizes that you are loading the project
from a different repository than the one originally used and that is
considered an error. Metacello signals a **MetacelloConflictingProjectError**.

To avoid the **MetacelloConflictingProjectError** you use the
`onConflict:` block and send `useNew` to the exception to use the new project
or `useExisting` to preserve the loaded state`.

## Project upgrades initiated by dependent proejcts

If we return to the earlier example where we have loaded Seaside 3.1.2
into our image:

```Smalltalk
Metacello image
configuration: 'Seaside3';
version: '3.1.2';
load.
```

and then attempt to load SeasideRest which requires Seaside 3.0.7:

```Smalltalk
Metacello image
configuration: 'SeasideRest';
version: #'stable';
load.
```

In the absence of locks, Metacello will silently upgrade the Seaside
project to Seaside 3.0.7. If you'd like to explicitly track Seaside
upgrades, you can use `onUpgrade:`:

```Smalltalk
Metacello image
configuration: 'SeasideRest';
version: #'stable';:w
onUpgrade: [:ex :existing :new |
existing baseName = 'Seaside30'
ifTrue: [
Transcript cr; show: 'Seaside30 upgraded to: ', new versionString ].
ex pass ].
load.
```

If you would like to explicitly prevent the upgrade (without using a
lock) you can do the following:

```Smalltalk
Metacello image
configuration: 'SeasideRest';
version: #'stable';
onUpgrade: [:ex :existing :new |
existing baseName = 'Seaside30'
ifTrue: [ ex disallow ].
ex pass ].
load.
```

If we assume that you have already loaded Seaside 3.0.9
into our image:

```Smalltalk
Metacello image
configuration: 'Seaside30';
version: '3.0.9';
load.
```

and then attempt to load SeasideRest which requires version Seaside 3.0.7:

```Smalltalk
Metacello image
configuration: 'SeasideRest';
version: #'stable';
load.
```
Metacello will silently ignore the downgrade request for Seaside and
leave Seaside 3.0.9 installed in the image.

If you want to have Seaside 3.0.9 downgraded then you used the `onDowngrade:` block

```Smalltalk
Metacello image
configuration: 'SeasideRest';
version: #'stable';
onDowngrade: [:ex :existing :new |
existing baseName = 'Seaside30'
ifTrue: [ ex allow ].
ex pass ].
load.
```

and Seaside 3.0.7 will be loaded.

[1]: MetacelloScriptingAPI.md
[2]: http://www.lukas-renggli.ch/blog/gofer
[3]: MetacelloScriptingAPI.md#repository-descriptions
Expand Down
2 changes: 1 addition & 1 deletion tests/userGuide.st
Original file line number Diff line number Diff line change
Expand Up @@ -203,7 +203,7 @@ Metacello image
on: Warning
do: [:ex |
Transcript cr; show: ex description.
ex resume ]
ex resume ].

TravisCISuccessNoFailure
value: 'TravisCISuccess.txt'.

0 comments on commit 6b9134c

Please sign in to comment.