View source for Documentation/4.6/Developers/Versioning

<noinclude>{{documentation/versioncheck}}</noinclude>
<!-- 
= 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 [http://nsis.sourceforge.net/Download 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 [http://slicer.cdash.org slicer.cdash.org] and [http://download.slicer.org download.slicer.org] to be available to the community.

You need to create a script following the template [http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/CMake/SlicerDashboardScript.TEMPLATE.cmake?view=markup Slicer/CMake/SlicerDashboardScript.TEMPLATE.cmake]. Change the following variables <code>WITH_PACKAGES</code> to <code>TRUE</code> and <code>SCRIPT_MODE</code> to <code>experimental</code> 

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: <code>slicer-vX.Y.Z-YEAR-MONTH-DAY</code> where 
* <code>X.Y.Z</code> corresponds to the version of the fork project
* <code>YEAR-MONTH-DAY</code> corresponds to the date of the last official commit of the fork project.

For example, in case of the [https://github.com/Slicer/VTK Slicer/VTK] fork, the branch <code>slicer-v6.2.0-2015-03-02</code> 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: <code>slicer-vX.Y-YEAR-MONTH-DAY-REV</code> where 

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

For example: <code>slicer-v6.2.0-2015-02-24-70bad0e</code>

=== 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:

<pre>
git shortlog sha_before..sha_after --no-merges
</pre>

where <code>sha_before</code> and <code>sha_after</code> are the first seven charachers of the SHA.

Here is an example of commit updating <code>External_VTKv6.cmake</code> in Slicer:

<pre>
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.
</pre>

Source: [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=25160 r25160]

==== Caveats ====

* For the commit title, prefer something like <code>ENH: Update VTK to ...</code> instead of <code>ENH: Update VTK git tag to ...</code>

* If there is only commit in the update, it is reasonable to copy the message. For example, see [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=24693 r24693]. 

* If the copied message reference the sha1 of its project (e.g VTK), change it to this form <code>org/proj@sha</code>. For example, see [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=24693 r24693].

* If there is a long list of changes return by <code>git shortlog</code>, make sure to copy the full list. Before the list, consider also adding a short summary of the "interesting" changes. For example, see [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=25068 r25068]

= Slicer Package naming scheme =
{{ambox|text=The following information is for Slicer maintainers only}}

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

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&lt;REV&gt;''' 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

{| class="wikitable"
! style="font-weight: bold;" | File name
! style="font-weight: bold;" | date
! style="font-weight: bold;" | build type
! style="font-weight: bold;" | 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.


{| class="wikitable"
! style="font-weight: bold;" | File name
! style="font-weight: bold;" | date
! style="font-weight: bold;" | build type
! style="font-weight: bold;" | branch
! style="font-weight: bold;" | 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 : <ul><li>next commit on master would increment minor version to start new dev cycle</li><li>creation of maintenance branch 4.6</li></ul>
|-
| ...                                          || ...        || ...     || ... || ...
|-
| 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 <code>Extensions-XYZ-Nightly</code> and <code>Extensions-XYZ-Continuous</code> tracks on CDash

*