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.

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.

Create release dashboard scripts

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

Commit message: Update Documentation to X.Y

For example: r22407

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)

Step 5: 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

Tag 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
    • See file /var/www/midas3/core/configs/database.local.ini for password
    • Choose midas database: use midas
  • 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);

Version NA-MIC data tree

1. Create an account on the extension server and obtain an API Key. You will then use your midas login and api key to substitute <YOUR-MIDAS-LOGIN> and <YOUR-MIDAS-APIKEY> in the examples.

2. If not already done, go to NA-MIC community and click on Join community

3. Send an email on the developer list asking to be added to the DataManager group on NA-MIC community. That will grant you read/write permissions to the Data folder and sub-folders.

4. Install prerequisites

   $ sudo pip install pydas
   

5. Identify id of the Data folder. For example 301

6. Create X.Y data tree based Nightly one

   $ cd /path/to/Slicer/Base/Python/slicer/release
   $ python midasdata.py --url=http://slicer.kitware.com/midas3 --data_id=301 \
     --email=<YOUR-MIDAS-LOGIN> --apikey=<YOUR-MIDAS-APIKEY> --source_version=Nightly --dest_version=X.Y
   
   Versioning of the NA-MIC Data tree for release X.Y...
   Versioning Modules...
   [...]
   Versioning Modules...[DONE]
   Versioning Application...
   Creating folder X.Y under Application directory
   Duplicating subfolders from Nightly to X.Y...
   Duplicating subfolders from Nightly to X.Y...[DONE]
   Versioning Application...[DONE]
   Versioning of the NA-MIC Data tree for release X.Y...[DONE]
   
   

Update external website

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

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