Documentation/Nightly/Developers/Versioning

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

How to create a Slicer package

Locally on your machine

After Slicer correctly build and test, to create a binary package on mac/unix:

$ cd Slicer-Superbuild/Slicer-build
$ make package

For Visual Studio on Windows, the inner Slicer (not superbuild) solution file contains a 'PACKAGE' project, just build it. You might have to install NSIS prior.

On Mac OS X, a 'dmg' file is generated, on unix it's a tar.gz archive and on Windows it's a exe installer.

Automatically expose it to the Slicer community

CTest can automatically create a package and upload it on slicer.cdash.org and download.slicer.org to be available to the community.

You need to create a script following the template Slicer/CMake/SlicerDashboardScript.TEMPLATE.cmake. Change the following variables WITH_PACKAGES to TRUE and SCRIPT_MODE to experimental

Then you can run your script:

$ ctest -S /path/to/SlicerPackageScript.cmake -VV > /path/to/logs.txt 2>&1

Please note that the source and build directories should not be located in /usr. The libraries would be considered by the packaging mechanism as "system" libraries.

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

[              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-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-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-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-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

Extension package - Naming scheme

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

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 where X.Y.Z corresponds to the version of the project.

For example, in case of the SlicerVTK fork, the branch slicer-v5.10.1 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-YEAR-MONTH-DAY-vX.Y where X.Y corresponds to the fork release.

Feature freeze

Usually ~1 month before release.

Prerequisites

• Update modules documentation link in help section (loadable, scripted and cli)
  • And some html links in Welcome module (Modules/Loadable/SlicerWelcome/Resources/HTML)
  • Update CLI XML description files

Release-candidate

Since there all development occurs on master, each time version is updated, two commits will be required.

Step 1

<RC> corresponds to the release candidate number. It is greater or equal to one.

• In CMakeLists.txt, uncomment and set:
  • Slicer_VERSION_TWEAK to 0
  • Slicer_VERSION_RC to 1, 2 or 3

• ... and if this is the first release candidate, update at least one these variables:
  • Slicer_VERSION_MAJOR
  • Slicer_VERSION_MINOR
  • Slicer_VERSION_PATCH

• Commit message: Slicer X.Y.Z-rc<RC>

Step 2

• Generate packages based on REVISION associated with step1.

Step 3

• In CMakeLists.txt, comment Slicer_VERSION_TWEAK so that the next builds will contain the date associated with the last commit.
• Commit message: Begin post-X.Y.Z-rc<RC> development

Release

Since there all development occurs on master, each time version is updated, two commits will be required.

Step1

• In CMakeLists.txt,
  • uncomment and set Slicer_VERSION_TWEAK to 0ode>

• ... and if this no release candidate has been made, update at least one these variables:
  • Slicer_VERSION_MAJOR
  • Slicer_VERSION_MINOR
  • Slicer_VERSION_PATCH

• Commit message: Slicer X.Y.Z

Step2

• Generate packages based on REVISION associated with step1.
• Tag the repository:

 svn copy -r<REVISION> http://svn.slicer.org/Slicer4/trunk  \
      http://svn.slicer.org/Slicer4/tags/Slicer-X-Y  \
     -m "ENH: Tag of X.Y.Z release based on r<REVISION>."
 

Step3

• In CMakeLists.txt, comment and set:
  • Slicer_VERSION_TWEAK to 0 so that the next builds will contain the date associated with the last commit.
  • Slicer_VERSION_RC to 0

• Commit message: Begin post-X.Y.Z development</code

Post release

Create a release branch

svn copy -r <REVISION> http://svn.slicer.org/Slicer4/trunk http://svn.slicer.org/Slicer4/branches/Slicer-X-Y

Backport commit into release branch

The following steps will lead to the creation of new git-svn clone having to branch:

• git-svn
• git-svn-XY

Reference: http://www.dmo.ca/blog/20070608113513/

Step 1: Checkout sources

git clone git://github.com/Slicer/Slicer.git Slicer-X.Y
cd Slicer-X.Y
git svn init http://svn.slicer.org/Slicer4/trunk
git update-ref refs/remotes/git-svn refs/remotes/origin/master
git checkout master
git svn rebase

Step 2: Add release branch remote

Edit .git/config, and in addition to the existing 'git-svn' remote, add the following one:

[svn-remote "svn-XY"]
   url = http://svn.slicer.org/Slicer4/branches/Slicer-X-Y
   fetch = :refs/remotes/git-svn-XY

Step 3: Pull associated SVN branch

git svn fetch git-svn-XY -r <REVISION>
git checkout -b master-XY git-svn-XY

Step 4: Backport

We can now cherry pick commit associated with master (trunk) into master-XY (Slicer-X-Y)

Step5: Create a patch release

Generate ChangeLog

• See gitlog2changelog.py. More details here.

• Update Release Details page using generated ChangeLog

Update Mantis

• "Release" current target
• Create new target
• Check the "fixed in" fields

Midas

Relocate release packages

• If needed, create a X.Y.Z folder in Slicer/Packages/Application/Release
  • Copy uploaded packages into the folder created above
  • Identify the item_id associated with uploaded packages. For example: 11926, 11925, 11927, 11992
  • SSH connect to jcfr@slicer.kitwarein.com
  • Connect to mysql using mysql -u midas -p
  • List packages associated with identified items and check they are the appropriate ones:
    • select * from slicerpackages_package as p , item as i where i.item_id = p.item_id and p.item_id in (11926, 11925, 11927, 11992);
  • Set release field
    • update slicerpackages_package set `release`="4.2.2-1" where item_id in (11926, 11925, 11927, 11992);

Update external website

See http://en.wikipedia.org/wiki/3DSlicer