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

From Slicer Wiki
Jump to: navigation, search
(4.1 -> Nightly)
 
 
(93 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
= How to create a Slicer package=
+
<noinclude>{{documentation/versioncheck}}</noinclude>
−
== locally on your machine ==
+
<!--
 +
= How to create a Slicer package =
 +
 
 +
== Locally on your machine ==
 +
 
 
After Slicer correctly build and test, to create a binary package on mac/unix:
 
After Slicer correctly build and test, to create a binary package on mac/unix:
 +
 
  $ cd Slicer-Superbuild/Slicer-build
 
  $ cd Slicer-Superbuild/Slicer-build
 
  $ make package
 
  $ 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.
 
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.
 
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
+
 
 +
== 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.
 
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>  
 
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:
 
Then you can run your script:
−
  $ ctest -S /path/to/SlicerPackagecript.cmake -VV > /path/to/logs.txt 2>&1
+
  $ 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.
 
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 ==
 +
 +
See [[Documentation/Nightly/Developers/ProjectForks]]
  
 
= Slicer Package naming scheme =
 
= Slicer Package naming scheme =
Line 34: Line 51:
  
 
== Example of linux 64bits packages ==
 
== 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
+
=== Proposal #1 ===
−
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
+
Include revision number in package name
−
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
+
{| class="wikitable"
−
Slicer-4.0.1-rc2-2012-01-12-linux-amd64  2012-01-12  development  nightly build after the release candidate
+
! style="font-weight: bold;" | File name
−
Slicer-4.0.1-linux-amd64                 2012-01-14   release     release of Slicer 4.0.1
+
! style="font-weight: bold;" | date
−
Slicer-4.0.1-2012-01-20-linux-amd64     2012-01-20  development  nightly build after 4.0.1
+
! style="font-weight: bold;" | build type
−
Slicer-4.0.1-1-linux-amd64               2012-01-28   release     tweak version 1 of Slicer 4.0.1
+
! style="font-weight: bold;" | note
−
Slicer-4.0.2-linux.amd64                 2012-06-05   release    release of Slicer 4.0.2
+
|-
 +
| 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
 +
|}
 +
 
 +
=== 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 =
 
= Extension package - Naming scheme =
−
{{documentation/underconstruction}}
 
−
= To do when versioning =
 
−
== At feature freeze (~1 month before release)==
 
−
* Create Slicer-4.[X+1] branch in SlicerVTK
 
−
** Make sure all commits are backported into VTK.
 
−
** Start from official VTK release branch or trunk (not recommanded)
 
−
** Try slicer with no Slicer.ini
 
  
−
== pre release & release ==
+
* Create <code>Extensions-XYZ-Nightly</code> and <code>Extensions-XYZ-Continuous</code> tracks on CDash
−
* Update modules documentation link in help section (loadable, scripted and cli)
 
−
** And some html links in Welcome module (Modules/Loadable/SlicerWelcome/Resources/HTML)
 
−
* Release commit with message: "ENH: Slicer 4.X.Y"
 
−
** In '''Slicer4/CMakeLists.txt''', update <code>Slicer_VERSION_MAJOR</code>, <code>Slicer_VERSION_MINOR</code>, <code>Slicer_VERSION_PATCH</code>. Uncomment and set <code>Slicer_VERSION_TWEAK</code> to 0, <code>Slicer_VERSION_RC</code>...
 
−
* commit with message: "ENH: Begin post-4.X.Y development"
 
−
** In '''Slicer4/CMakeLists.txt''', comment <code>Slicer_VERSION_TWEAK</code> so the next builds will contain the day of build.
 
  
−
== post release ==
+
*
−
* Package machines
 
−
** switch to branch (make sure at least you are on trunk otherwise)
 
−
*** <code>svn switch http://svn.slicer.org/Slicer4/branches/Slicer-4-1-QtTesting</code>
 
−
** update source to release revision
 
−
*** <code>cd Slicer; svn update -r19609</code>
 
−
** delete build directory to force rebuild
 
−
*** <code>cd Slicer-package; rm -rf *</code>
 
−
** build, package and upload with cmake
 
−
*** <code>cd DashboardScripts; ./factory-make-package.sh</code>
 
−
*** make sure LEGACY CLIs is ON, EMSegment needs BSplineToDeformationField.
 
−
* Generate ChangeLog using [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
 
−
* In Mantis
 
−
** "Release" current target
 
−
** Create new target
 
−
** Check the "fixed in" fields
 

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"