Documentation/4.6/Developers/Versioning

From Slicer Wiki
Jump to: navigation, search
Home < Documentation < 4.6 < Developers < Versioning


For the latest Slicer documentation, visit the read-the-docs.



Versioning

Project fork

While Slicer specific patches related to dependent project (i.e. VTK) are integrated upstream, it is not uncommon to build Slicer against a Slicer specific fork of the project.

For example: https://github.com/Slicer/VTK

Patches for tagged release

For each version of the project requiring some specific patches, a branch following that convention will be created: slicer-vX.Y.Z-YEAR-MONTH-DAY where

  • X.Y.Z corresponds to the version of the fork project
  • YEAR-MONTH-DAY corresponds to the date of the last official commit of the fork project.

For example, in case of the Slicer/VTK fork, the branch slicer-v6.2.0-2015-03-02 has been created.

Patches for development branch

In this case, since there is no tag associated with the branch, the Slicer specific patch should be added to a branch named using the date of the commit parent of the Slicer branch: slicer-vX.Y-YEAR-MONTH-DAY-REV where

  • X.Y corresponds to the fork release
  • REV corresponds to either the first 7 chars of git hash or SVN revision (for example r1234)
  • YEAR-MONTH-DAY corresponds to the date of the last official commit of the fork project

For example: slicer-v6.2.0-2015-02-24-70bad0e

Adding patches to the fork

When adding new patches to the fork, prefer direct commits or cherry-picked commits over merge commits. Avoiding merge commits makes it easier to rebase the fork against a new upstream revision.

Commit message

The following command should be used to list changes:

git shortlog sha_before..sha_after --no-merges

where sha_before and sha_after are the first seven charachers of the SHA.

Here is an example of commit updating External_VTKv6.cmake in Slicer:

ENH: Update VTK to handle default values for array parameters in python
    
Without this commit, one must specify parameters like (,int array[3]=0) when
the method is called from python.

$ git shortlog 1c30cb0..4b9957b --no-merges
David Gobbi (2):
      Fix wrapping pointer parameters with default value 0.
      Handle default values for array parameters in python.

Source: r25160

Caveats

  • For the commit title, prefer something like ENH: Update VTK to ... instead of ENH: Update VTK git tag to ...
  • If there is only commit in the update, it is reasonable to copy the message. For example, see r24693.
  • If the copied message reference the sha1 of its project (e.g VTK), change it to this form org/proj@sha. For example, see r24693.
  • If there is a long list of changes return by git shortlog, make sure to copy the full list. Before the list, consider also adding a short summary of the "interesting" changes. For example, see r25068

Slicer Package naming scheme

Slicer-<MAJOR_VERSION>.<MINOR_VERSION>.<PATCH_VERSION>[-rc{1|2|3...}][-<TWEAK_VERSION>][-<DATE>][-svn<REV>][-dirty]-<ARCH>-<PLATFORM>

There are 2 types of builds, releases and developments:

Release
Special builds made on a given revision (e.g. r19033: "ENH: Slicer 4.0.1")
Don't contain date or revision number.
The optional suffix -rc{1|2|3|...} identifies the release candidates leading to a final release.
Eventually, a tweak number can be added (e.g. 4.0.1-1)
Development
Nightly or experimental builds
Contains suffixes after the major.minor.patch version
The suffix svn<REV> allows to identify the revision associated with the current package.
The -dirty prefix indicates if the package has been generated from a locally modified source tree.

Example of linux 64bits packages

Proposal #1

Include revision number in package name

File name date build type note
Slicer-4.0.0-linux-amd64 2011-11-24 release release of Slicer 4.0.0
Slicer-4.0.0-2011-12-10-svn100-linux-amd64 2011-11-25 development nightly build after 4.0.0
Slicer-4.0.1-rc1-linux-amd64 2012-01-04 release release candidate 1 of Slicer 4.0.1
Slicer-4.0.1-rc1-2012-01-05-svn150-linux-amd64 2012-01-05 development nightly build after the release candidate
Slicer-4.0.1-rc2-linux-amd64 2012-01-11 release release candidate 2 of Slicer 4.0.1
Slicer-4.0.1-rc2-2012-01-12-svn200-linux-amd64 2012-01-12 development nightly build after the release candidate
Slicer-4.0.1-linux-amd64 2012-01-14 release release of Slicer 4.0.1
Slicer-4.0.1-2012-01-20-svn236-linux-amd64 2012-01-20 development nightly build after 4.0.1
Slicer-4.0.1-1-linux-amd64 2012-01-28 release tweak version 1 of Slicer 4.0.1
Slicer-4.0.2-linux.amd64 2012-06-05 release release of Slicer 4.0.2

Proposal #2

  • Increment minor version after each release, remove the concept of release candidate and tweak version.
  • With the transition to git workflow where branching is easier, after each release, the minor version in the trunk would be increased by one.
  • Patch release would be done using the maintenance branch associated with any given release.


File name date build type branch note
Slicer-4.5.0-1-linux-amd64 2015-12-11 release 4.5 tweak version 1 of Slicer 4.5.0
Slicer-4.6.0-2016-01-30-svn24950-linux-amd64 2016-01-30 development master nightly build after 4.5.0
... ... ... ... ...
Slicer-4.6.0-2016-02-06-svn25174-linux-amd64 2016-02-06 development master nightly build after 4.5.0
Slicer-4.5.1-2016-02-06-svn25175-linux-amd64 2016-02-06 development 4.5 manual build after 4.5.0-1
Slicer-4.5.1-linux-amd64 2015-02-07 release 4.5 patch version 1 of Slicer 4.5.0
... ... ... ... ...
Slicer-4.6.0-2016-03-05-svn25174-linux-amd64 2016-02-05 development master nightly build after 4.5.0
Slicer-4.6.0-linux-amd64 2016-03-06 release master release of 4.6.0 :
  • next commit on master would increment minor version to start new dev cycle
  • creation of maintenance branch 4.6
... ... ... ... ...
Slicer-4.6.0-2016-03-07-svn25180-linux-amd64 2016-03-07 development master nightly build after 4.6.0

Extension package - Naming scheme

  • Create Extensions-XYZ-Nightly and Extensions-XYZ-Continuous tracks on CDash