Squeak – Monticello – How to use Branches

The solution is really simple. Don't use branches. Just register your
author initials and use the current timestamp as the version number.
YYYYMMDDhhmm. That's it.



Monticello refers to Monticello packages by their name. So it is a good
idea to have a package name that is globally unique. This can be achieved
by using branches.

If the branch name starts with the unique author identification then
anything that follows it can be assumed to be in the domain of the author
to decide and manage. Much like web domains or the package hierarchy in
Java.

The mcz files in a repository can use Monticello branch names. This way
multiple versions of the project can be kept in one repository and be
easily distinguished from one another.

Monticello package version numbers are branch local. Meaning each branch
starts its numbering from one. And can even be omitted.


So how do we create a globally unique branch name that helps us to manage
branches under our control? Let's look at a possible naming scheme.




A Simple Scheme

When we are saving a package version, we have to manually edit the
suggested filename according to this template.

To get a unique name it is enough to combine
- a package name
- a branch name consisting solely of your unique author identification
(your author initials, say mva,
registered at http://source.squeak.org/inbox.html)
- a timestamp in the required author field (say 201703031038)
- omit the numeric version (0 will be assumed).

For example in
SQLite3.mva-201703031038.mcz
we have
SQLite3 for package name,
.mva- for branch name
-201703031038 for author (YYYYMMDDhhmm),
no numeric version, 0 assumed.

In fact, you could just start using timestamps in this format for the
version number and you do not have to use branches at all.

If you do, you can stop worrying whether you already have a version 2 of
this particular package before saving. You can just go ahead and save with
the current timestamp as version number and your author initials and rest
assured that this will be a unique filename. You can copy those files
around and everything will just work out fine. Unlike if you had a version
2 lurking somewhere and then you save another version 2 and at some point
in time it will come back to bite you. Monticello will get confused
thinking there can be only one version 2. You will get confused too because
you will forget about that other version 2 you have created and then wonder
how come there are two versions 2.

You can designate a directory a 'branch' (a development branch, not a
Monticello branch name). Add that directory to Monticello as a directory
repository. Packages you put there will sort nicely in Repository Browser
according to the version number (ordering by version number is the default
order there). Version number being the timestamp they will sort according
to the times the packages were created.

Compare
SQLite3.mva-201703031038.mcz
and
SQLite3-mva.201703031038.mcz
.

SQLite3.mva-201703031038.mcz
Package name: SQLite3
Branch name: mva
Author: 201703031038
Version: 0

SQLite3-mva.201703031038.mcz
Package name: SQLite3
Branch name: none
Author: mva
Version: 201703031038


Keep reading for some background information.

Assuming we only save one version of a given package per minute, a minute
resolution in the timestamp is enough.

We can save a version of multiple packages in the same minute and their
names will not collide because the package name will disambiguate them.

For example,
SQLite3-Core.mva-201703031038.mcz
SQLite3-Tests.mva-201703031038.mcz
do not collide even though they share the same timestamp and branch name.

If multiple developers agree to use this scheme they can share package
files without worrying that their names would collide. Even copy them
to a master repository without messing things up.

For example,
SQLite3-Tests.mva-201703031038.mcz
SQLite3-Tests.tbn-201703031038.mcz
do not collide even though they share the same timestamp and package name.

If you disable the preference setting
'Browse branched package versions separately' 
you can see all versions of a package in a repository in Repository Browser
grouped together under the package name regardless of branches.

A More Involved Scheme.

For example in the Monticello package name
SQLite3.mva-squeak5.0-rel1.0-2017_02_12.1.mcz
the package name is
SQLite3
the branch is
mva-squeak5.0-rel1.0
the author identification is
2017_02_12
and version number is
1

A branch is determined from the Monticello package name like this:
1) strip the shortest suffix starting with dash
2) from the result of 1) strip the shortest prefix ending with dot

In other words the branch name starts with the first dot (before the last
dash) and ends with the last dash.

The 'before the last dash' part is there because a dot after the last dash
is used to find the numeric version (a string of digits, possibly with
leading zeros).

Additional characters can follow the numeric version. They have to start
with a non-digit and can not include the dash. They can include additional
dots. Also numeric characters are allowed (except for the first one).

What comes after the last dash is supposed to be author identification
followed by a dot and a numeric version.

The author identification part is expected to be present.

At least one dash must appear in the package filename.

The numeric version does not have to be present in which case it is assumed
to be 0.

The author identification part and numeric version parts are used to order
the list of package names in Repository Browser. The numeric version does
not have to be present. The author identification does have to be present
but can represent a timestamp instead for example.

The branch name can contain additional dots and dashes.

Let's look at an example.


Let's take
SQLite3.mva-squeak5.0-rel1.0-2017_02_12.1.mcz
as an example.
Here 1) yields
SQLite3.mva-squeak5.0-rel1.0
stripping the suffix
-2017_02_12.1.mcz
And 2) yields
mva-squeak5.0-rel1.0
stripping the prefix
SQLite3.


Instead of author identification in the name, a date of the commit is
used in the form YYYY_MM_DD. This way the name contains the date of the
last commit - the version number of which follows it. This makes the
filenames sort in the order of the branches and commit dates on the
branches.

The author is still recorded inside the archive. Just not in the filename.

Ordering in Repository browser by author can show you the timeline of the
commits across branches.

The branch naming convention used here is
1) branch author identification
2) target identification with version number
3) development or release version with version number

Let's take
SQLite3.mva-squeak5.0-rel1.0-2017_02_12.1.mcz
as an example.
The branch name here is
mva-squeak5.0-rel1.0
as explained above.
We get
mva
as branch author identification
squeak5.0
as target identification with version number
rel1.0
as release version with version number

The target identification with version number
squeak5.0
is the intended system. The package is compatible with, tested on, and
meant to run on this version. It might run on other other versions and/or
systems but there are no guarantees.

For a possible scheme for version numbers see the link on Semantic Versioning.


A corporate branch of the SQLite3 package run by the Acme company could look like 
SQLite3.acme-squeak5.0-rel1.0-2017_02_12.1.mcz
How this relates to developer mva's own branch
SQLite3.mva-squeak5.0-rel1.0-2017_02_12.1.mcz
is up to him.

External Links

Versioning with Monticello

Pharo Smalltalk Users - branching with monticello

Monticello: Workflow for simultaneous collaborative development / correctly numbering a version when copying to remote repository

Semantic Versioning

Advertisements

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s