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

From Slicer Wiki
Jump to: navigation, search
 
(One intermediate revision by the same user 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
 
−
 
 
−
=== 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 =
 
= Slicer 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"