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

From Slicer Wiki
Jump to: navigation, search
(→‎Release: document update process for __version__.py)
(→‎Release-candidate: document update process for __version__.py, improve step organization)
Line 71: Line 71:
 
<ol start="1" style="list-style-type: decimal;">
 
<ol start="1" style="list-style-type: decimal;">
  
<li><p>In <code>CMakeLists.txt</code>, uncomment and set:
+
<li><p>Update the Slicer version information for the release candidate:</p>
 +
<ol style="list-style-type: lower-roman;">
 +
<li><p>In <code>CMakeLists.txt</code>, uncomment and set:</p>
 
*<code>Slicer_VERSION_TWEAK</code> to <code>0</code>
 
*<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>
+
*<code>Slicer_VERSION_RC</code> to <code><RC></code>
 
+
<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>
<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>Re-run CMake in order to update <code>Utilities/Scripts/SlicerWizard/__version__.py</code>.</li>
 +
<li><p>Commit the above changes using this message:</p>
 +
ENH: Slicer X.Y.Z-rc<RC>
 +
</li>
 +
</ol>
 
</li>
 
</li>
  
<li><p>Commit <code>CMakeLists.txt</code> changes using this message:</p><pre>ENH: Slicer X.Y.Z-rc<RC></pre></li>
+
<li>Generate packages based on REVISION associated with step 1.</li>
  
<li><p>Generate packages based on REVISION associated with step1.</p></li>
+
<li><p>Update the Slicer version information for the development:</p>
 
+
<ol style="list-style-type: lower-roman;">
<li>
+
<li>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.</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>Re-run CMake in order to update <code>Utilities/Scripts/SlicerWizard/__version__.py</code>.</li>
 
</li>
 
</li>
 
+
<li><p>Commit the above changes using this message:</p>
<li>
+
ENH: Begin post-X.Y.Z-rc<RC> development
<p>Commit <code>CMakeLists.txt</code> changes using this message:</p> <pre>ENH: Begin post-X.Y.Z-rc<RC> development</pre>
 
 
</li>
 
</li>
 +
</ol>
  
 
</ol>
 
</ol>

Revision as of 19:24, 14 March 2014

Home < Documentation < Nightly < Developers < Versioning


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



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

UnderConstruction.png

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.

<RC> corresponds to the release candidate number. It is greater or equal to one.

  1. Update the Slicer version information for the release candidate:

    1. In CMakeLists.txt, uncomment and set:

      • Slicer_VERSION_TWEAK to 0
      • Slicer_VERSION_RC to <RC>

      ...and if this is the first release candidate, update at least one these variables: Slicer_VERSION_MAJOR, Slicer_VERSION_MINOR, Slicer_VERSION_PATCH

    2. Re-run CMake in order to update Utilities/Scripts/SlicerWizard/__version__.py.
    3. Commit the above changes using this message:

      ENH: Slicer X.Y.Z-rc<RC>
      
  2. Generate packages based on REVISION associated with step 1.
  3. Update the Slicer version information for the development:

    1. In CMakeLists.txt, comment Slicer_VERSION_TWEAK so that the next builds will contain the date associated with the last commit.
    2. Re-run CMake in order to update Utilities/Scripts/SlicerWizard/__version__.py.
    3. Commit the above changes using this message:

      ENH: 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.

  1. Update the Slicer version information for the release:

    1. In CMakeLists.txt, uncomment and set Slicer_VERSION_TWEAK to 0

      ...and if this no release candidate has been made, update at least one these variables: Slicer_VERSION_MAJOR, Slicer_VERSION_MINOR, Slicer_VERSION_PATCH

    2. Re-run CMake in order to update Utilities/Scripts/SlicerWizard/__version__.py.
  2. Commit the above changes using this message:

    ENH: Slicer X.Y.Z
    
  3. 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>."
    
  4. Update the Slicer version information for the development:

    1. 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
    2. Re-run CMake in order to update Utilities/Scripts/SlicerWizard/__version__.py.
  5. Commit the above changes using this message:

    ENH: Begin post-X.Y.Z development
    

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>"


 svn checkout http://svn.slicer.org/Slicer4/branches/Slicer-X-Y

Generate 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. Simulate creation of X.Y data folders based Nightly ones

    $ 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 )
    
    
  7. Create X.Y data tree based Nightly ones

    $ 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 Slicer wiki

The copy of the pages associated with the Nightly namespace into the X.Y namespace is done using the convenience python module mwdoc.

  1. Check with <email>jchris.fillionr@kitware.com</email> to get the credential associated with UpdateBot user.

  2. Copy Nightly pages into X.Y pages.

    $ cd ~/Projects
    
    $ sudo pip install mwclient
    
    $ git clone git://github.com/jcfr/mwdoc
    
    $ cd mwdoc
    
    $ python
    
    >>> import mwdoc
    >>> 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'
      
  3. Update Template:Documentation/nextversion

  4. Update Template:Documentation/currentversion

  5. Update Template:Documentation/versionlist

  6. Update FAQ

  7. Update Documentation

  8. Update Documentation/Release

  9. Update Documentation/Release/Announcements

  10. Update Documentation/UserTraining

  11. Update Documentation/UserOrientation

  12. Update Documentation/DeveloperOrientation

CDash

  1. Create new CDash groups for extension submissions associated with X.Y release:

    Extensions-X.Y-Nightly
    Extensions-X.Y-Continuous
    

Update external website

Backport commit into release branch

The following steps will lead to the creation of new git-svn clone having two branches:

  • 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 svn-XY
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

UnderConstruction.png


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