Difference between revisions of "Documentation/Nightly/Developers/Versioning"

From Slicer Wiki
Jump to: navigation, search
 
(34 intermediate revisions by 4 users not shown)
Line 31: Line 31:
 
== Project fork ==
 
== 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.
+
See [[Documentation/Nightly/Developers/ProjectForks]]
  
−
For example: https://github.com/Slicer/VTK
+
= Slicer Package naming scheme =
 +
{{ambox|text=The following information is for Slicer maintainers only}}
  
−
=== Patches for tagged release ===
+
<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>
  
−
For each version of the project requiring some specific patches, a branch following that convention will be created: <code>slicer-vX.Y.Z</code> where <code>X.Y.Z</code> corresponds to the version of the project.
+
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.
  
−
For example, in case of the SlicerVTK fork, the branch <code>slicer-v5.10.1</code> has been created.
+
== Example of linux 64bits packages ==
−
 
 
−
=== 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-YEAR-MONTH-DAY-vX.Y</code> where <code>X.Y</code> corresponds to the fork release.
 
−
 
 
−
== Create release dashboard scripts ==
 
−
 
 
−
{{wip}}
 
−
 
 
−
== 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: <code>Update Documentation to X.Y</code>
 
−
 
 
−
For example: [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=22407 r22407]
 
−
 
 
−
== Release-candidate ==
 
−
 
 
−
Since there all development occurs on <code>master</code>, each time version is updated, two commits will be required.
 
−
 
 
−
<code><RC></code> corresponds to the release candidate number. It is greater or equal to one.
 
−
 
 
−
<ol start="1" style="list-style-type: decimal;">
 
−
 
 
−
<li><p>In <code>CMakeLists.txt</code>, uncomment and set:
 
−
*<code>Slicer_VERSION_TWEAK</code> to <code>0</code>
 
−
*<code>Slicer_VERSION_RC</code> to <code>1</code>, <code>2</code> or <code>3</code></p>
 
−
 
 
−
<p>... and if this is the first release candidate, update at least one these variables: <code>Slicer_VERSION_MAJOR</code>, <code>Slicer_VERSION_MINOR</code>, <code>Slicer_VERSION_PATCH</code></p>
 
−
</li>
 
−
 
 
−
<li><p>Commit <code>CMakeLists.txt</code> changes using this message:</p><pre>ENH: Slicer X.Y.Z-rc<RC></pre></li>
 
−
 
 
−
<li><p>Generate packages based on REVISION associated with step1.</p></li>
 
−
 
 
−
<li>
 
−
<p>In <code>CMakeLists.txt</code>, comment <code>Slicer_VERSION_TWEAK</code> so that the next builds will contain the date associated with the last commit.</p>
 
−
</li>
 
−
 
 
−
<li>
 
−
<p>Commit <code>CMakeLists.txt</code> changes using this message:</p> <pre>ENH: Begin post-X.Y.Z-rc<RC> development</pre>
 
−
</li>
 
−
 
 
−
</ol>
 
−
 
 
−
== Release ==
 
−
 
 
−
Since there all development occurs on <code>master</code>, each time version is updated, two commits will be required.
 
−
 
 
−
<ol start="1" style="list-style-type: decimal;">
 
−
 
 
−
<li><p>In <code>CMakeLists.txt</code>, uncomment and set <code>Slicer_VERSION_TWEAK</code> to <code>0</code></p>
 
−
 
 
−
<p>... and if this no release candidate has been made, update at least one these variables: <code>Slicer_VERSION_MAJOR</code>, <code>Slicer_VERSION_MINOR</code>, <code>Slicer_VERSION_PATCH</code></p>
 
−
</li>
 
−
 
 
−
<li><p>Commit <code>CMakeLists.txt</code> changes using this message:</p><pre>ENH: Slicer X.Y.Z</pre></li>
 
−
 
 
−
<li>
 
−
<p>Generate packages based on REVISION associated with step1.</p>
 
−
<p>Tag the repository:</p>
 
−
<pre>
 
−
  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>."
 
−
</pre>
 
−
</li>
 
−
 
 
−
<li><p>In <code>CMakeLists.txt</code>, comment and set:</p>
 
−
* <code>Slicer_VERSION_TWEAK</code> to <code>0</code> so that the next builds will contain the date associated with the last commit.
 
−
* <code>Slicer_VERSION_RC</code> to <code>0</code>
 
−
</li>
 
−
 
 
−
<li><p>Commit <code>CMakeLists.txt</code> changes using this message:</p> <pre>ENH: Begin post-X.Y.Z development</pre></li>
 
−
 
 
−
</ol>
 
−
 
 
−
== 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 \
 
−
  -m "ENH: Branching from trunk to Slicer-X-Y at <REVISION>"
 
−
 
 
−
=== Backport commit into release branch ===
 
−
 
 
−
The following steps will lead to the creation of new git-svn clone having two branches:
 
−
* <code>git-svn</code>
 
−
* <code>git-svn-XY</code>
 
−
 
 
−
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 <code>.git/config</code>, 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 <code>master-XY</code> (Slicer-X-Y)
 
−
 
 
−
==== Step 5: Create a patch release ====
 
−
 
 
−
{{wip}}
 
−
 
 
−
<!--
 
−
Slicer trunk: Update Major/Minor/Patch version to match latest release
 
−
-->
 
−
 
 
−
=== Generate ChangeLog ===
 
−
 
 
−
* See [https://raw.github.com/cryos/avogadro/master/scripts/gitlog2changelog.py gitlog2changelog.py]. More details [http://blog.cryos.net/archives/202-Git-and-Automatic-ChangeLog-Generation.html 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 [http://slicer.kitware.com/midas3/folder/274 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 <code>jcfr@slicer.kitwarein.com</code>
 
−
** Connect to mysql using <code>mysql -u midas -p</code>
 
−
*** See file <code>/var/www/midas3/core/configs/database.local.ini</code> for password
 
−
*** Choose midas database: <code>use midas</code>
 
−
** List packages associated with identified items and check they are the appropriate ones:
 
−
*** <code>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);</code>
 
−
** Set release field
 
−
*** <code>update slicerpackages_package set `release`="4.2.2-1" where item_id in (11926, 11925, 11927, 11992);</code>
 
−
 
 
−
==== Version NA-MIC data tree ====
 
−
 
 
−
<ol start="1" style="list-style-type: decimal;">
 
−
 
 
−
<li><p>[[Documentation/{{documentation/version}}/Developers/Tutorials/ObtainExtensionServerApiKey|Create an account on the extension server and obtain an API Key]]. You will then use your midas login and api key to substitute <code><YOUR-MIDAS-LOGIN></code> and <code><YOUR-MIDAS-APIKEY></code> in the examples.</p></li>
 
−
 
 
−
<li><p>If not already done, go to [http://slicer.kitware.com/midas3/community/23 NA-MIC community] and click on <code>Join community</code></p></li>
 
−
 
 
−
<li><p>Send an email on the developer list asking to be added to the <code>DataManager</code> group on NA-MIC community. That will grant you read/write permissions to the <code>Data</code> folder and sub-folders.</p></li>
 
−
 
 
−
<li><p>Install prerequisites</p>
 
−
<pre>
 
−
$ sudo pip install pydas
 
−
</pre></li>
 
−
 
 
−
<li><p>Identify <code>id</code> of the <code>Data</code> folder. For example [http://slicer.kitware.com/midas3/folder/301 301]</p></li>
 
−
 
 
−
<li><p>Simulate creation of <code>X.Y</code> data folders based <code>Nightly</code> ones</p>
 
−
<pre>
 
−
$ 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 --dry-run
 
−
Application ( folder_id: 302 )
 
−
'-Nightly ( folder_id: 831 )
 
−
'-'-Testing ( folder_id: 832 )
 
−
'-'-'-Baseline ( folder_id: 889 )
 
−
'-'-'-'-DiffusionTensorImagingTutorial.png ( item_id: 12067 )
 
−
'-'-'-'-NeurosurgicalPlanningTutorial.png ( item_id: 12066 )
 
−
'-'-'-'-SlicerTestingTest.png ( item_id: 17760 )
 
−
'-'-'-Input ( folder_id: 833 )
 
−
'-'-'-'-AtlasTests ( folder_id: 834 )
 
−
'-'-'-'-'-2012-10-26-BrainAtlas.mrb ( item_id: 10276 )
 
−
[...]
 
−
Module: VotingBinaryHoleFillingImageFilter ( folder_id: 1491 )
 
−
'-Nightly ( folder_id: 1491 )
 
−
'-'-Testing ( folder_id: 1492 )
 
−
'-'-'-Baseline ( folder_id: 1493 )
 
−
'-'-'-'-VotingBinaryHoleFillingImageFilterTest.nhdr ( item_id: 103418 )
 
−
'-'-'-'-VotingBinaryHoleFillingImageFilterTest.raw.gz ( item_id: 103419 )
 
−
 
 
−
</pre>
 
−
</li>
 
−
 
 
−
<li><p>Create <code>X.Y</code> data tree based <code>Nightly</code> ones</p>
 
−
<pre>
 
−
$ 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]
 
−
 
 
−
</pre></li>
 
−
 
 
−
</ol>
 
−
 
 
−
=== Update Slicer wiki ===
 
−
 
 
−
The copy of the pages associated with the <code>Nightly</code> namespace into the <code>X.Y</code> namespace is done using the convenience python module [https://github.com/jcfr/mwdoc#readme mwdoc].
 
−
 
 
−
<ol start="1" style="list-style-type: decimal;">
 
−
 
 
−
<li><p>Check with <email>jchris.fillionr@kitware.com</email> to get the credential associated with <code>UpdateBot</code> user.</p></li>
 
−
 
 
−
<li>
 
−
  <p>Copy <code>Nightly</code> pages into <code>X.Y</code> pages.</p>
 
−
  <pre>
 
−
$ cd ~/Projects
 
  
−
$ sudo pip install mwclient
+
=== Proposal #1 ===
  
−
$ git clone git://github.com/jcfr/mwdoc
+
Include revision number in package name
  
−
$ cd mwdoc
+
{| 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
 +
|}
  
−
$ python
+
=== Proposal #2 ===
  
−
>>> import mwdoc
+
* Increment minor version after each release, remove the concept of release candidate and tweak version.
−
>>> doc = mwdoc.Documentation('slicer.org', '/slicerWiki/')
 
−
>>> doc.login('UpdateBot', 'XXXXXXX')
 
−
>>> doc.versionPages('Nightly', '4.3', ['Documentation', 'Template:Documentation'])
 
−
[INFO] Page successfully created: 'Documentation/4.3/Extensions/ErodeDilateLabel'
 
−
[...]
 
−
[INFO] Page successfully created: 'Template:Documentation/4.3/module-header'
 
−
[INFO] Page successfully created: 'Template:Documentation/4.3/module-section'
 
−
[INFO] Page successfully created: 'Template:Documentation/4.3/module/footer'
 
−
  </pre>
 
−
</li>
 
  
−
<li><p>Update [[Template:Documentation/nextversion]]</p></li>
+
* With the transition to git workflow where branching is easier, after each release, the minor version in the trunk would be increased by one.
  
−
<li><p>Update [[Template:Documentation/currentversion]]</p></li>
+
* Patch release would be done using the maintenance branch associated with any given release.
  
−
<li><p>Update [[Template:Documentation/versionlist]]</p></li>
 
  
−
<li><p>Update [[FAQ]]</p></li>
+
{| 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
 +
|}
  
−
<li><p>Update [[Documentation]]</p></li>
+
=== Proposal #3 ===
  
−
</ol>
+
* Package name remains unchanged: Slicer-X.Y.Z[-YYYY-MM-DD]-<arch>.<ext>
  
−
=== CDash ===
+
* Development build will end with an "odd" number
 +
** For example: 4.7, 4.9, 5.1, 5.3
 +
** Package name include the date: Slicer-X.Y.Z[-YYYY-MM-DD].<ext>
  
−
<ol start="1" style="list-style-type: decimal;">
+
* Stable release will end with an "even" number
−
<li><p>Create new CDash groups for extension submissions associated with <code>X.Y</code> release:</p>
+
** For example: 4.8, 5.0, 5.2
−
<pre>
+
** Package name do not include the date: Slicer-X.Y.Z.<ext>
−
Extensions-X.Y-Nightly
+
−
Extensions-X.Y-Continuous
+
* Install folder:
−
</pre></li>
+
** windows: Slicer X.Y.Z-YYYY-MM-DD  (remains the same)
 +
** macOS: Slicer.app -> Slicer-X.Y.Z-YYYY-MM-DD.app (add revision and date)
 +
** Linux: Slicer-X.Y.Z[-YYYY-MM-DD]-<arch> (remains the same)
  
−
</ol>
 
  
−
=== Update external website ===
 
  
−
See http://en.wikipedia.org/wiki/3DSlicer
+
==== Why ? ====
  
−
= Slicer Package naming scheme =
+
* Slicer is "released" daily (aka nightly build) and mixing these daily releases with stable releases under the same major.minor revision would be confusing for the users. We cannot expect users to learn different naming patterns to determine what kind of release (development/stable) they are installing and learning a complex logic of determining which version is more recent (e.g., which one is more recent 4.7.1-1 or 4.7.0-2017-08-29).
−
{{ambox|text=The following information is for Slicer maintainers only}}
+
* With this new scheme in place, we can unambiguously specify both stable/development branch and a specific version. This allows using simple major.minor tags in Mantis, documentation, forums, etc.
−
 
+
* It will be possible to distinguish between the pre- and the post- release. When we mention 4.8, it clearly relates to a version that contain all changes of 4.7.
−
<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>
+
* Semantic versioning not applicable to a complex application, maintaining backward compatibility is done as a best effort and often "minor" breaking changes are included after communicating with users or updating the user code.
−
 
 
−
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 ==
 
−
[              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 =
 
= Extension package - Naming scheme =

Latest revision as of 20:06, 23 October 2017

Home < Documentation < Nightly < Developers < Versioning


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



Versioning

Project fork

See Documentation/Nightly/Developers/ProjectForks

Slicer Package naming scheme

 The following information is for Slicer maintainers only 
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

Proposal #3

  • Package name remains unchanged: Slicer-X.Y.Z[-YYYY-MM-DD]-<arch>.<ext>
  • Development build will end with an "odd" number
    • For example: 4.7, 4.9, 5.1, 5.3
    • Package name include the date: Slicer-X.Y.Z[-YYYY-MM-DD].<ext>
  • Stable release will end with an "even" number
    • For example: 4.8, 5.0, 5.2
    • Package name do not include the date: Slicer-X.Y.Z.<ext>
  • Install folder:
    • windows: Slicer X.Y.Z-YYYY-MM-DD (remains the same)
    • macOS: Slicer.app -> Slicer-X.Y.Z-YYYY-MM-DD.app (add revision and date)
    • Linux: Slicer-X.Y.Z[-YYYY-MM-DD]-<arch> (remains the same)


Why ?

  • Slicer is "released" daily (aka nightly build) and mixing these daily releases with stable releases under the same major.minor revision would be confusing for the users. We cannot expect users to learn different naming patterns to determine what kind of release (development/stable) they are installing and learning a complex logic of determining which version is more recent (e.g., which one is more recent 4.7.1-1 or 4.7.0-2017-08-29).
  • With this new scheme in place, we can unambiguously specify both stable/development branch and a specific version. This allows using simple major.minor tags in Mantis, documentation, forums, etc.
  • It will be possible to distinguish between the pre- and the post- release. When we mention 4.8, it clearly relates to a version that contain all changes of 4.7.
  • Semantic versioning not applicable to a complex application, maintaining backward compatibility is done as a best effort and often "minor" breaking changes are included after communicating with users or updating the user code.

Extension package - Naming scheme

  • Create Extensions-XYZ-Nightly and Extensions-XYZ-Continuous tracks on CDash
Retrieved from "https://www.slicer.org/w/index.php?title=Documentation/Nightly/Developers/Versioning&oldid=56878"