ITK/How to make a Release: Difference between revisions

From KitwarePublic
< ITK
Jump to navigationJump to search
(Deprecate page)
 
(137 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{warning|1=The current authoritative resource is [https://github.com/InsightSoftwareConsortium/ITK/blob/master/Documentation/Maintenance/Release.md GitHub release documentation].}}
= How To Make an ITK Release =
= How To Make an ITK Release =


This page describes the sequence of steps required for making an ITK release
This page describes the sequence of steps required for making an ITK release. There are typically two feature releases a year, around December and June, and one to three bug fixes between feature releases.
 
== Update CMake version required in CMakeList.txt ==
 
edit CMakeLists.txt and find the variables


    CMAKE_MINIMUM_REQUIRED
== Bug fix release general steps ==
# Create tag (with GPG signature) for release. Do not forget to update ITK revision number in CMakeLists.txt.
# Create release notes: <pre>git shortlog --no-merges v4.11.0..release</pre>
# Write blog post in a google doc and share it with the Comm’ team.
# Use same text (2) to prepare mailing list message
# Create tarballs and upload them on SourceForge
# Send email to Comm’ team so they can update links to tarballs on [http://www.itk.org www.itk.org]. Verify that links work!
# Send email to mailing list (user, develop, community), add post in the [https://plus.google.com/u/0/communities/111375098792764998322 ITKBarCamp Google+ community] and publish blog post.


and set it to the latest stable release of CMake.
'''For details of each step, refer to the sections below.'''


== Update Version number in CMakeList.txt ==
== Integrate bug fixes in the release branch ==
* Update master and release branches
<pre>git fetch
git checkout master
git reset --hard origin/master
git checkout release
git reset --hard origin/release</pre>
* List differences between last release and current release branch
<pre>git shortlog --no-merges v4.10.0..release</pre>
* Merge bug fix commits in release. Topic branch should be named <bug-name>-for-release
** If topic branch was created from release branch, checkout topic in new branch (see command lines on gerrit)
** If topic branch was created on master, cherry-pick commit (see command line on gerrit) on a topic branch created off release. The commit will be visible twice in the history once release in merged into master.
** Merge new branch on release: <pre>git merge <bug-name>-for-release --no-ff</pre>
** Update gerrit: write “Merged to release.” in merged topic.
* Merge release into master (so master keeps track of release history)
<pre>git checkout master
git pull
git merge release
git push origin master release</pre>
* For patches that need to be merged to the "release-3.20" branch, they are first merged to release-3.20, then release-3.20 is merged to the release branch with 'git merge -s ours' to avoid a huge number of merge conflicts. Then, release is merged into master.


Edit CMakeLists.txt and find the variables
== Pre-tag activities ==


* SET(ITK_VERSION_MAJOR "2")
* Make sure to update the versions in the top level CMakeLists.txt as described below
* SET(ITK_VERSION_MINOR "2")
** For bugfix releases, this is done before the tag.  For feature releases, this is done after the final tag.
* SET(ITK_VERSION_PATCH "0")
* Make sure all new remote modules are built in by the Doxygen build
* Update the WikiExamples and SphinxExamples remote modules.


and update them according to the current release number.
== Tag the ITK repository ==
 
Commit this change to the CVS repository.
 
== Tag the Insight repository ==


Tagging the repository should only be done with the agreement of the developers after a tcon.
Tagging the repository should only be done with the agreement of the developers after a tcon.
Line 31: Line 52:
use the commmand  
use the commmand  


   cvs -q update -d -P -A
   git checkout master
  git pull


to make sure that your source tree is updated. This must correspond
to make sure that your source tree is updated. This must correspond
to a source tree that has been fully tested in the Dashboard.
to a source tree that has been fully tested in the Dashboard.
When tagging a bugfix release on the ''release'' branch, make sure to bump the ''ITK_VERSION_PATCH'' variable in the top level ''CMakeLists.txt'' before tagging.  When tagging a feature release, make sure to bump the ''ITK_VERSION_MINOR'' version on the ''master'' branch after tagging.


=== Tag with a branch point reference ===
=== Tag with a branch point reference ===
''Note:''  At this time, Brad King, Matt McCormick, Francois Budin, or Jean-Christophe Fillion-Robin are the person to do this because of their trusted GPG key.


In the source tree that you just updated, use the command
In the source tree that you just updated, use the command
 
  git tag -m "ITK 4.5-rc03" -s v4.5rc03 f9d99ca3ad00116393c4e2ce899beb00695ebb24


  cvs tag ITK-2-2-bp


where, of course you change -2-2- for the correct release number.
where, of course you change v4.5rc03 for the correct release number and the hash to the correct commit.


This tag before the branching point serves as a reference for future merges.
Push it to the repository


=== Tag and branch ===
  git push origin v4.5rc03


In the same source tree use the cvs command
=== Update the release branch ===


  cvs tag -b ITK-2-2
Update the release branch only during features releases after the tag for the release. Perform a fast-forward merge of master into release:


where, again, of course, you replace -2-2 with the appropriate release number.
  git checkout release
  git reset --hard origin/release
  git merge --ff-only <version tag>
  git push origin release
  git checkout master


The -b option will create a branch.
This will not create a new commit, only move the release branch to the tag, i.e. it will be fast forward.


=== Historical Note ===
For minor releases, merge release branch into master branch as for a normal commit, and resolve conflict (arising from mismatch in version number) by keeping master branch versions.


During releases 3.0 to 3.4 we used to do also a '''post-branch tag'''. This practice has now been deemed unnecessary and it is no longer recommended. The two tags described above will be sufficient for maintaining the branch and having a reference point before the branch.
== Mark the release as resolved on the issue tracker ==


[https://issues.itk.org/jira/plugins/servlet/project-config/ITK/versions Projects -> ITK -> Versions]


=== References ===
Schedule the next release, and update the [[ITK/Release Schedule | Release Schedule]] page.


For more details on CVS Management:
== Prepare Release Notes ==
https://www.kitware.com/KWWiki/index.php/CVS_Repository_Management#Creating_a_new_CVS_Branch


== Tag the InsightApplications repository ==
Release notes are prepared in a Google Doc.


The same sequence of steps used for Insight must be used for tagging and branching the module of InsightApplications
A list of authors and new authors can be computed with [https://gist.github.com/thewtex/5045b8e13b5d12b8fdcf this script].


== Tag CableSwig ==
Todo: Add more description of the structure of release notes.


CableSwig must be tagged with the same tag used for the ITK release.
This is usually done by Brad King at Kitware.


== Add New Remote Modules to Nightly Builds ==


== Prepare tarballs ==
Some builds may be difficult to add due to third-party dependencies.


Once the repository has been tagged, we CVS export its content using the tag in order to create .tar.gz and .zip files.
== Send Contributor Momentos ==


=== CVS Exporting ===
This file:


==== CVS login as anonymous ====
  https://github.com/thewtex/vtkGEB/blob/itk/itkgeb.stl


Create an empty directory, the use the CVS command for login
can be ordered from ShapeWays and sent to contributors. Deb Howell has generated excellent packaging.


  cvs -d :pserver:anonymous@www.itk.org:/cvsroot/Insight login
== Archive ExternalData ==


use "insight" as password
Set the environmental or CMake variable ''ExternalData_OBJECT_STORES'' to a local directory. E.g.


==== CVS checking out Insight ====
  export ExternalData_OBJECT_STORES=${HOME}/data


Then use the export CVS command with the tag of that release
Pre-populate the store with the contents of the 'InsightData' tarballs from a previous release. Once the tarball extracted, move the content of its subfolder called .ExternalData in your local ExternalData_OBJECT_STORES directory.


  cvs -d :pserver:anonymous@www.itk.org:/cvsroot/Insight checkout -r ITK-2-2 -d InsightToolkit-2.2.0  Insight
Then, from the ITK build directory, configure ITK, enable ''ITK_WRAP_PYTHON'', ''ITK_LEGACY_SILENT'' , ''BUILD_TESTING'' and ''BUILD_EXAMPLES''.


* the option -r defines the tag to be used for checked out
If you have previously enabled remote modules using the same ITK source directory, either verify that they are enabled in your
* the option -d creates a directory with a particular name. This directory name should match the number of the release
current build, or remove their source directory that has been added inside ITK source directory (Modules/Remote/{name_of_remote_module}).


==== CVS checking out InsightApplications ====
Build the ''ITKData'' target


Export also InsightApplications with the command
  make ITKData


  cvs -d :pserver:anonymous@www.itk.org:/cvsroot/Insight checkout -r ITK-2-2 -d InsightApplications-2.2.0  InsightApplications
This will download new testing data since the previous release.


Next, run the script from within the ITK source directory:


==== CVS checking out CableSwig ====
  ./Utilities/Maintenance/ContentLinkSynchronization.sh ${ExternalData_OBJECT_STORES}


Checkout CableSwig with the command
'''Do not use ''--cleanup'' as for the purpose of the GitHub resource, it is important to keep the older files: some are from older revisions of ITK, and people continue to use the older versions of ITK and request the testing data.'''


  cvs -d :pserver:anonymous@www.itk.org:/cvsroot/CableSwig checkout -r ITK-2-2  -d CableSwig-ITK-2.2.0 CableSwig
This is will verify all contents, fully populate the ''MD5/'' and ''SHA512/'' directories in the object store, and create any missing ''.md5'' or ''.sha512'' content links. If any new content link files are created, commit the result.


Next, archive the data on data.kitware.com. Create a folder, e.g. ''4.11'', in [https://data.kitware.com/#collection/57b5c9e58d777f126827f5a1/folder/57b672b48d777f10f269651a ITK/ITKTestingData]


=== Create Tarballs ===
  ./Utilities/Maintenance/ArchiveTestingDataOnGirder.py --object-store ${HOME}/data --parent-id <the-girder-id-of-the-folder-created> --api-key <your-girder-user-api-key>


==== InsightToolkit tarball ====
This script requires the ''girder-client'' Python package install from Girder master, November 2016 or later, (Girder >2.0.0).


create the tar file with the command
Run the script


  tar -c -f InsightToolkit-2.2.0.tar   InsightToolkit-2.2.0
   ./Utilities/Maintenance/ArchiveTestingDataOnMidas.py


use the maximum compression with gzip
to upload the testing data from a local store on the ITK https://midas3.kitware.com/midas/ and http://slicer.kitware.com/midas3/ Community.


  gzip -9  InsightToolkit-2.2.0.tar
This script requires that [http://pydas.readthedocs.org/en/latest/ pydas] is installed. Note: If you get the following error message: <pre>pydas.exceptions.InvalidPolicy: 'Request failed with HTTP status code 200, Midas Server error code -151, and response content {"stat":"fail","message":"Invalid policy or itemid","code":"-151"}'</pre> make sure you have the permissions to write in the ITK collection on the Midas server.


That should produce a file named


  InsightToolkit-2.2.0.tar.gz
Archive the InsightData contents on ITK's file server at Kitware


  rsync -v -r /tmp/InsightToolkit-4.9.0/.ExternalData/MD5/ public:/projects/Insight/WWW/InsightWeb/files/ExternalData/MD5/


==== InsightApplications tarball ====
Update the data archive at https://github.com/InsightSoftwareConsortium/ITKTestingData


create the tar file with the command
== Prepare tarballs ==


  tar -c -f InsightApplications-2.2.0.tar  InsightApplications-2.2.0
==== InsightToolkit tarball ====


use the maximum compression with gzip
Once the repository has been tagged, we use the following script in the repository to create the tarballs:


  gzip -9  InsightApplications-2.2.0.tar
    Utilities/Maintenance/SourceTarball.bash --tgz --txz --zip


That should produce a file named
Note: tarballs can be created from a specific commit. The user can manually specify the version of ITK used to name the output files:


  InsightApplications-2.2.0.tar.gz
    Utilities/Maintenance/SourceTarball.bash -v 4.10.1 11f687df0347df9c1fee757745c1f1976ec3cbfe


After the tarballs have been uploaded to SourceForge, check their MD5 sums (the "i" info button on Sourceforge.net and locally with the 'md5sum' command). Also, download them from SourceForge and run an Experimental build on Linux, OSX, and Windows.


==== CableSwig tarball ====
== ITK Software Guide ==


create the tar file with the command
Bump the ITK version in Superbuild/ExternalITKv4.cmake.


  tar -c -f CableSwig-ITK-2.2.0.tar  CableSwig-ITK-2.2.0
Set the ''DRAFT_WATERMARK'' CMake varable to OFF to remove the draft watermark.


use the maximum compression with gzip
Set the ''PDF_QUALITY_LEVEL'' CMake configuration option to "Screen" for the electronic version and "Printer" for the print version.


  gzip -9  CableSwig-ITK-2.2.0.tar
Turn on ''GENERATE_HTML''.


That should produce a file named
To create ItkSoftwareGuide.pdf to put at itk.org/ItkSoftwareGuide.pdf from InsightSoftwareGuide-Book{1,2}-4.X.0.pdf, use pdftk


  CableSwig-ITK-2.2.0.tar.gz
  pdftk ITKSoftwareGuide-Book1.pdf ITKSoftwareGuide-Book2.pdf cat output /tmp/ItkSoftwareGuide.pdf


=== Creating Zip files on Windows ===
=== Prepare the print version ===


Follow the above instructions for exporting the source files in a Windows machine. This can be done with a Cygwin that has been configured at installation-time for using a DOS file system, not a UNIX filesystem.
Set the ''PDF_QUALITY_LEVEL'' to "Printer", and rebuild.


Once you have both directories: Insight and InsightApplications, right click on each of them and select the option "send to compressed file".
Remove the junk initial page, and then also one of the blank pages so pages fall on "left-side / right-side" as formatted.


=== Generating Doxygen Documentation ===
  pdftk ITKSoftwareGuide-Book1.pdf cat 2-3 5-end output /tmp/ITKSoftwareGuide-Book1.pdf
  pdftk ITKSoftwareGuide-Book2.pdf cat 2-3 5-end output /tmp/ITKSoftwareGuide-Book2.pdf


* Run CMake in the binary build and enable  BUILD_DOXYGEN
=== Update the HTML pages ===
* Do Configure and Generate in CMake
* Go to the binary directory
* Type  "make Documentation"
* Move into the directory Utilities/ ( cd Utilities/ )
* Rename the Doxygen directory as DoxygenInsightToolkit-3.4.0 (of course with the appropriate release number)
* Tar it with the command: tar -cf DoxygenInsightToolkit-3.4.0.tar DoxygenInsightToolkit-3.4.0
* Compress it with the command: gzip -9 DoxygenInsightToolkit-3.4.0.tar


Historical note: Before ITK 3.8, The documentation used to be generated in a directory called Documentation/Doxygen.
rsync the newly generated pages to the web server.


== Copy the files to the FTP directory in public.kitware.com ==
<pre>
rsync -rt html/ kitware@public:/projects/Insight/WWW/InsightWeb/ITKSoftwareGuide/html
</pre>


  scp  InsightToolkit-2.4.0.tar.gz        kitware@public:/projects/Insight/WWW/InsightDocuments/Web/files/v2.4
== ITK Sphinx Examples ==
  scp  InsightApplications-2.4.0.tar.gz    kitware@public:/projects/Insight/WWW/InsightDocuments/Web/files/v2.4
  scp  InsightToolkit-2.4.0.zip            kitware@public:/projects/Insight/WWW/InsightDocuments/Web/files/v2.4
  scp  InsightApplications-2.4.0.zip      kitware@public:/projects/Insight/WWW/InsightDocuments/Web/files/v2.4
  scp  DoxygenInsightToolkit-2.4.0.tar.gz  kitware@public:/projects/Insight/WWW/InsightDocuments/Web/files/v2.4
  scp  DoxygenInsightToolkit-2.4.0.zip    kitware@public:/projects/Insight/WWW/InsightDocuments/Web/files/v2.4
  scp  CableSwig-2.4.0.tar.gz              kitware@public:/projects/Insight/WWW/InsightDocuments/Web/files/v2.4
  scp  CableSwig-2.4.0.zip                kitware@public:/projects/Insight/WWW/InsightDocuments/Web/files/v2.4


== Copy the files to SourceForge ==
Bump the Superbuild ITK version in Superbuild/External-ITK.cmake.


This is to be done only by
Rendered versions (epub, pdf, html) can be downloaded from the [http://itk.org/ITKExamples/Documentation/Download/index.html download page] and rename them.


* Ken Martin at Kitware
Create the source tarballs.
* Luis Ibanez at Kitware


=== Using Dav ===
Set the prefix and tag:


You can use the following command to log in:
  tag=$(git describe)
  prefix=InsightSphinxExamples-4.10.0


  cadaver https://frs.sourceforge.net/l/lu/luisibanez/uploads
Generate .zip and .tar.gz:


followed by user name and password
  git archive --format=tar --prefix=${prefix}/ --output=${prefix}.tar ${tag}
  gzip -9  ${prefix}.tar
  git archive --format=zip -9 --prefix=${prefix}/ --output=${prefix}.zip ${tag}


Then you can use commands similar to the ones that were available to FTP clients.
== ITK Wiki Examples ==


For example:
Download the latest examples:


  put InsightToolkit-3.10.1.tgz
  version=4.12.0


=== Using Rsync ===
  wget -O ITKWikiExamples-master.zip https://github.com/InsightSoftwareConsortium/ITKWikiExamples/archive/master.zip
  unzip ITKWikiExamples-master.zip
  mv ITKWikiExamples-master InsightWikiExamples-${version}
  zip -r InsightWikiExamples-${version}.zip InsightWikiExamples-${version}
  tar cvf InsightWikiExamples-${version}.tar InsightWikiExamples-${version}
  gzip -9 InsightWikiExamples-${version}.tar


Or you can use the following single-line command to upload a file:
== Generating Doxygen Documentation ==


  rsync -avP -e ssh InsightToolkit-3.10.1.tgz luisibanez@frs.sourceforge.net:uploads/
'''Note''': links to the nightly generated Doxygen can be found in the footer of the Doxygen HTML pages.
Use the files to upload and create InsightDoxygenDocTag-4.11.0.gz, InsightDoxygenXml-4.11.0.tar.gz, InsightDoxygenDocHtml-4.11.0.tar.gz.s


the great thing with rsync is that you can restart from where you stopped (incremental ftp).
Prior to the release, new Remote Modules should be enabled in the Doxygen build's configuration.


=== Using Upload Web page ===


You could also use your Web Browser to go to the following upload page
* Run CMake in the binary build and enable  BUILD_DOXYGEN
* Do Configure and Generate in CMake
* Go to the binary directory
* Type  "make Documentation"
* Move into the directory Utilities/ ( cd Utilities/ )
* Rename the Doxygen directory as DoxygenInsightToolkit-3.4.0 (of course with the appropriate release number)
* Tar it with the command: tar -cf DoxygenInsightToolkit-3.4.0.tar DoxygenInsightToolkit-3.4.0
* Compress it with the command: gzip -9 DoxygenInsightToolkit-3.4.0.tar


    https://frs.sourceforge.net/webupload
Historical note: Before ITK 3.8, The documentation used to be generated in a directory called Documentation/Doxygen.


and also provide user name and password
* In Public do:
** Copy documentation to:    /projects/Insight/Doxygen
*** Create a subdirectory Insight34-doxygen/Documentation/Doxygen
*** The final directory will look like: /projects/Insight/Doxygen/Insight34-doxygen/Documentation/Doxygen
*** and at that level copy the "html" directory and the InsightToolkit.tag file.
** Create symbolic link at:  /projects/Insight/WWW/InsightWeb
** ('''DEPRECATED''' - last release 4.1) <s>Create symbolic link at:  /projects/Insight/WWW/InsightDocuments/Web </s>


Then user the "Browse.." button in order to select the files to upload, and finally click on the "Upload" button to actually upload the file to the Sourceforge server.
== Copy the files to the FTP directory in public.kitware.com ==


== Update the HTML Download page ==
  scp  InsightData-4.12.0.tar.gz                  kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  scp  InsightData-4.12.0.tar.xz                  kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  scp  InsightData-4.12.0.zip                    kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  scp  InsightToolkit-4.12.0.tar.gz              kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  scp  InsightToolkit-4.12.0.tar.xz              kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  scp  InsightToolkit-4.12.0.zip                  kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  <s>scp  InsightApplications-4.12.0.tar.gz          kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12</s>
  <s>scp  InsightApplications-4.12.0.zip            kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12</s>
  scp  InsightDoxygenDocHtml-4.12.0.tar.gz        kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  scp  InsightDoxygenDocTag-4.12.0.tar.gz        kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  scp  InsightDoxygenDocXml-4.12.0.tar.gz        kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  scp  ItkSoftwareGuide.pdf                      kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  scp  InsightSoftwareGuide-Book1-4.12.0.pdf      kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  scp  InsightSoftwareGuide-Book2-4.12.0.pdf      kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  scp  InsightSoftwareGuideHtml-4.12.0.tar.gz    kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  scp  InsightWikiExamples-4.12.0.tar.gz          kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
  scp  InsightWikiExamples-4.12.0.zip            kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12


Contact Niki Russell at Kitware in order to
  ssh kitware@public
  cd /projects/Insight/WWW/InsightWeb
  rm ItkSoftwareGuide.pdf
  ln -s files/v4.12/ItkSoftwareGuide.pdf ItkSoftwareGuide.pdf


* Update the Download HTML page: http://www.itk.org/ITK/resources/software.html
== Copy the files to SourceForge ==
* Produce a press release


== Update the HTML Documentation page ==
This is to be done only by


=== Documentation.htm ===
* Ken Martin at Kitware
* Brad King at Kitware
* Matt McCormick at Kitware
* Francois Budin at Kitware
* Brad Lowekamp at NLM


Go to your checkout of InsightDocuments
=== Using The New (2010) Interface ===


and to the subdirectory Web/HTML
Go to this page


cvs update it
  https://sourceforge.net/downloads/itk/itk/


edit the file
and provide user name and password


  Documentation.htm
Then


* Use the "Add Folder" button to create a folder for the release.
* Click on the folder to open it
* Use the "Add File" button to upload files. The interface allows you to select multiple files for simultaneous upload.


The content should be updated to point to the Doxygen documentation of the current release
After uploading, make sure to check the hashes on the uploads.  These can be shown with the "(i)" button next to the file.


=== Installing Doxygen documentation in public.kitware.com ===
'''Large files''', like the Doxygen HTML tarball, '''need to be uploaded with scp''', a la:


The DoxygenInsightToolkit-X.X.X.tar.zip should be expanded in public.kitware.com
  scp InsightDoxygenDocHtml-4.7.0.tar.gz mmmccormic@frs.sourceforge.net:/home/frs/project/itk/itk/4.7/InsightDoxygenDocHtml-4.7.0.tar.gz
in such a way that the Doxygen documentation becomes available at


  http://www.itk.org/Doxygen34/html/index.html
== Update the HTML Download page ==


see directory: /projects/Insight/Doxygen
Contact Communications at Kitware in order to


Once installed the documentation should be in
* Update the Download HTML page: http://www.itk.org/ITK/resources/software.html
* Produce a press release
* Update http://itk.org/ItkSoftwareGuide.pdf


  /projects/Insight/Doxygen/Insight32-doxygen/Documentation/Doxygen
== Update the HTML Documentation page ==


(with the appropriate release number...)
=== Documentation.htm ===


Create symbolic link in the directory:
Contact Communications at Kitware in order to update the page:


  /projects/Insight/WWW/InsightDocuments/Web
  http://www.itk.org/ITK/help/documentation.html


The link will look like:
The content should be updated to point to the Doxygen documentation of the current release
 
  Doxygen34 -> ../../../Doxygen/Insight34-doxygen/Documentation/Doxygen//


== Update the Release Notes in the Wiki ==
== Update the Release Notes in the Wiki ==


=== Update "What's New in Release x.x" Wiki Page ===
=== Add entry for next planned release ===


From a Linux system, cd into an Insight binary directory and run
Delete the old entry and add a new entry in the [[ITK/Release Schedule| scheduled releases page]]


./NewSince.csh StartDateOfRelease EndDateofRelease
=== Update the Releases page ===


For example, Release 2.0
Add the "What's New" and "What's Changed" entries to the [[ITK/Releases| Releases]] page.
./NewSince.csh "August 10, 2004" "February 4, 2005"


This will produce a file in @ITK_BIN_DIR@/Testing/Temporary/NewSince.txt that can be pasted into the Wiki page ITK_RELEASE_X_X. Update the main ITK Wiki page to include a link to this new page.
===Update "What's New in Release x.x" Wiki Page ===


Update this web-page with the e-mail sent to the ITK mailing indicating the notable changes and other important information about the release.


=== Update "What has Changed since previous release" ===
=== Update "What has Changed since previous release" ===


From a Linux system, cd into an Insight binary directory and run  
From a Linux system, cd into an ITK Git directory and run  
 
./ChangedSince.csh StartDateOfRelease EndDateofRelease


For example, Release 2.0
  git shortlog --topo-order --no-merges v4.0.0..v4.1.0
./ChangedSince.csh "August 10, 2004" "February 4, 2005"


This will produce a file in @ITK_BIN_DIR@/Testing/Temporary/ChangedSince.txt that can be pasted into the Wiki page ITK_RELEASE_X_X. Update the main ITK Wiki page to include a link to this new page.
Delete the KWRobot time stamp commits.


== Update Insight Journal ==
== <s>Update Insight Journal</s> (deprecated)==


Contact Zack and request to do the following:
<s>Contact Zack and request to do the following:


* Install new ITK version in the Insight Journal testing environment
* Install new ITK version in the Insight Journal testing environment
* Update IJMacros.txt: Add the just released version of ITK
* Update IJMacros.txt: Add the just released version of ITK</s>
 


== Update MANTIS bug tracker ==
== Update JIRA issue tracker ==


* Create a new version to make possible for users to report bug pertaining to that specific ITK release
* Create a new version to make possible for users to report bug pertaining to that specific ITK release
** This is particularly important for being able to commit changes to the branch, since all change must have a bug number associated with it.
** Create the next release target milestone with Administration -> ITK -> Versions -> Add
 
** Release the current release milestone with Agile -> Classic ... -> Right click the release on the left -> Release


== Further Testing ==
== Further Testing ==
Line 318: Line 380:
The purpose of this testing is to replicate the experience that a user may have when trying the new release.
The purpose of this testing is to replicate the experience that a user may have when trying the new release.


This means that a number of ITK developers should download the tarballs or do CVS checkouts with the release tag, and build the toolki t in as many configuration as possible.
This means that a number of ITK developers should download the tarballs or do Git checkouts with the release tag, and build the toolkit in as many configuration as possible.
 
== Notes ==


* ITK minor releases (patch) do not have a tagged release candidate.
{{ITK/Template/Footer}}
{{ITK/Template/Footer}}

Latest revision as of 14:13, 16 October 2019

Warning: The current authoritative resource is GitHub release documentation.

How To Make an ITK Release

This page describes the sequence of steps required for making an ITK release. There are typically two feature releases a year, around December and June, and one to three bug fixes between feature releases.

Bug fix release general steps

  1. Create tag (with GPG signature) for release. Do not forget to update ITK revision number in CMakeLists.txt.
  2. Create release notes:
    git shortlog --no-merges v4.11.0..release
  3. Write blog post in a google doc and share it with the Comm’ team.
  4. Use same text (2) to prepare mailing list message
  5. Create tarballs and upload them on SourceForge
  6. Send email to Comm’ team so they can update links to tarballs on www.itk.org. Verify that links work!
  7. Send email to mailing list (user, develop, community), add post in the ITKBarCamp Google+ community and publish blog post.

For details of each step, refer to the sections below.

Integrate bug fixes in the release branch

  • Update master and release branches
git fetch
git checkout master
git reset --hard origin/master
git checkout release
git reset --hard origin/release
  • List differences between last release and current release branch
git shortlog --no-merges v4.10.0..release
  • Merge bug fix commits in release. Topic branch should be named <bug-name>-for-release
    • If topic branch was created from release branch, checkout topic in new branch (see command lines on gerrit)
    • If topic branch was created on master, cherry-pick commit (see command line on gerrit) on a topic branch created off release. The commit will be visible twice in the history once release in merged into master.
    • Merge new branch on release:
      git merge <bug-name>-for-release --no-ff
    • Update gerrit: write “Merged to release.” in merged topic.
  • Merge release into master (so master keeps track of release history)
git checkout master
git pull
git merge release
git push origin master release
  • For patches that need to be merged to the "release-3.20" branch, they are first merged to release-3.20, then release-3.20 is merged to the release branch with 'git merge -s ours' to avoid a huge number of merge conflicts. Then, release is merged into master.

Pre-tag activities

  • Make sure to update the versions in the top level CMakeLists.txt as described below
    • For bugfix releases, this is done before the tag. For feature releases, this is done after the final tag.
  • Make sure all new remote modules are built in by the Doxygen build
  • Update the WikiExamples and SphinxExamples remote modules.

Tag the ITK repository

Tagging the repository should only be done with the agreement of the developers after a tcon.

Update your repository with

use the commmand

  git checkout master
  git pull

to make sure that your source tree is updated. This must correspond to a source tree that has been fully tested in the Dashboard.

When tagging a bugfix release on the release branch, make sure to bump the ITK_VERSION_PATCH variable in the top level CMakeLists.txt before tagging. When tagging a feature release, make sure to bump the ITK_VERSION_MINOR version on the master branch after tagging.

Tag with a branch point reference

Note: At this time, Brad King, Matt McCormick, Francois Budin, or Jean-Christophe Fillion-Robin are the person to do this because of their trusted GPG key.

In the source tree that you just updated, use the command

 git tag -m "ITK 4.5-rc03" -s v4.5rc03 f9d99ca3ad00116393c4e2ce899beb00695ebb24


where, of course you change v4.5rc03 for the correct release number and the hash to the correct commit.

Push it to the repository

 git push origin v4.5rc03

Update the release branch

Update the release branch only during features releases after the tag for the release. Perform a fast-forward merge of master into release:

 git checkout release
 git reset --hard origin/release
 git merge --ff-only <version tag>
 git push origin release
 git checkout master

This will not create a new commit, only move the release branch to the tag, i.e. it will be fast forward.

For minor releases, merge release branch into master branch as for a normal commit, and resolve conflict (arising from mismatch in version number) by keeping master branch versions.

Mark the release as resolved on the issue tracker

Projects -> ITK -> Versions

Schedule the next release, and update the Release Schedule page.

Prepare Release Notes

Release notes are prepared in a Google Doc.

A list of authors and new authors can be computed with this script.

Todo: Add more description of the structure of release notes.


Add New Remote Modules to Nightly Builds

Some builds may be difficult to add due to third-party dependencies.

Send Contributor Momentos

This file:

 https://github.com/thewtex/vtkGEB/blob/itk/itkgeb.stl

can be ordered from ShapeWays and sent to contributors. Deb Howell has generated excellent packaging.

Archive ExternalData

Set the environmental or CMake variable ExternalData_OBJECT_STORES to a local directory. E.g.

 export ExternalData_OBJECT_STORES=${HOME}/data

Pre-populate the store with the contents of the 'InsightData' tarballs from a previous release. Once the tarball extracted, move the content of its subfolder called .ExternalData in your local ExternalData_OBJECT_STORES directory.

Then, from the ITK build directory, configure ITK, enable ITK_WRAP_PYTHON, ITK_LEGACY_SILENT , BUILD_TESTING and BUILD_EXAMPLES.

If you have previously enabled remote modules using the same ITK source directory, either verify that they are enabled in your current build, or remove their source directory that has been added inside ITK source directory (Modules/Remote/{name_of_remote_module}).

Build the ITKData target

 make ITKData

This will download new testing data since the previous release.

Next, run the script from within the ITK source directory:

 ./Utilities/Maintenance/ContentLinkSynchronization.sh ${ExternalData_OBJECT_STORES}

Do not use --cleanup as for the purpose of the GitHub resource, it is important to keep the older files: some are from older revisions of ITK, and people continue to use the older versions of ITK and request the testing data.

This is will verify all contents, fully populate the MD5/ and SHA512/ directories in the object store, and create any missing .md5 or .sha512 content links. If any new content link files are created, commit the result.

Next, archive the data on data.kitware.com. Create a folder, e.g. 4.11, in ITK/ITKTestingData

 ./Utilities/Maintenance/ArchiveTestingDataOnGirder.py --object-store ${HOME}/data --parent-id <the-girder-id-of-the-folder-created> --api-key <your-girder-user-api-key>

This script requires the girder-client Python package install from Girder master, November 2016 or later, (Girder >2.0.0).

Run the script

 ./Utilities/Maintenance/ArchiveTestingDataOnMidas.py

to upload the testing data from a local store on the ITK https://midas3.kitware.com/midas/ and http://slicer.kitware.com/midas3/ Community.

This script requires that pydas is installed. Note: If you get the following error message:

pydas.exceptions.InvalidPolicy: 'Request failed with HTTP status code 200, Midas Server error code -151, and response content {"stat":"fail","message":"Invalid policy or itemid","code":"-151"}'

make sure you have the permissions to write in the ITK collection on the Midas server.


Archive the InsightData contents on ITK's file server at Kitware

 rsync -v -r /tmp/InsightToolkit-4.9.0/.ExternalData/MD5/ public:/projects/Insight/WWW/InsightWeb/files/ExternalData/MD5/

Update the data archive at https://github.com/InsightSoftwareConsortium/ITKTestingData

Prepare tarballs

InsightToolkit tarball

Once the repository has been tagged, we use the following script in the repository to create the tarballs:

   Utilities/Maintenance/SourceTarball.bash --tgz --txz --zip

Note: tarballs can be created from a specific commit. The user can manually specify the version of ITK used to name the output files:

   Utilities/Maintenance/SourceTarball.bash -v 4.10.1 11f687df0347df9c1fee757745c1f1976ec3cbfe

After the tarballs have been uploaded to SourceForge, check their MD5 sums (the "i" info button on Sourceforge.net and locally with the 'md5sum' command). Also, download them from SourceForge and run an Experimental build on Linux, OSX, and Windows.

ITK Software Guide

Bump the ITK version in Superbuild/ExternalITKv4.cmake.

Set the DRAFT_WATERMARK CMake varable to OFF to remove the draft watermark.

Set the PDF_QUALITY_LEVEL CMake configuration option to "Screen" for the electronic version and "Printer" for the print version.

Turn on GENERATE_HTML.

To create ItkSoftwareGuide.pdf to put at itk.org/ItkSoftwareGuide.pdf from InsightSoftwareGuide-Book{1,2}-4.X.0.pdf, use pdftk

 pdftk ITKSoftwareGuide-Book1.pdf ITKSoftwareGuide-Book2.pdf cat output /tmp/ItkSoftwareGuide.pdf

Prepare the print version

Set the PDF_QUALITY_LEVEL to "Printer", and rebuild.

Remove the junk initial page, and then also one of the blank pages so pages fall on "left-side / right-side" as formatted.

 pdftk ITKSoftwareGuide-Book1.pdf cat 2-3 5-end output /tmp/ITKSoftwareGuide-Book1.pdf
 pdftk ITKSoftwareGuide-Book2.pdf cat 2-3 5-end output /tmp/ITKSoftwareGuide-Book2.pdf

Update the HTML pages

rsync the newly generated pages to the web server.

rsync -rt html/ kitware@public:/projects/Insight/WWW/InsightWeb/ITKSoftwareGuide/html

ITK Sphinx Examples

Bump the Superbuild ITK version in Superbuild/External-ITK.cmake.

Rendered versions (epub, pdf, html) can be downloaded from the download page and rename them.

Create the source tarballs.

Set the prefix and tag:

 tag=$(git describe)
 prefix=InsightSphinxExamples-4.10.0

Generate .zip and .tar.gz:

 git archive --format=tar --prefix=${prefix}/ --output=${prefix}.tar ${tag}
 gzip -9  ${prefix}.tar
 git archive --format=zip -9 --prefix=${prefix}/ --output=${prefix}.zip ${tag}

ITK Wiki Examples

Download the latest examples:

 version=4.12.0
 wget -O ITKWikiExamples-master.zip https://github.com/InsightSoftwareConsortium/ITKWikiExamples/archive/master.zip 
 unzip ITKWikiExamples-master.zip
 mv ITKWikiExamples-master InsightWikiExamples-${version}
 zip -r InsightWikiExamples-${version}.zip InsightWikiExamples-${version}
 tar cvf InsightWikiExamples-${version}.tar InsightWikiExamples-${version}
 gzip -9 InsightWikiExamples-${version}.tar

Generating Doxygen Documentation

Note: links to the nightly generated Doxygen can be found in the footer of the Doxygen HTML pages. Use the files to upload and create InsightDoxygenDocTag-4.11.0.gz, InsightDoxygenXml-4.11.0.tar.gz, InsightDoxygenDocHtml-4.11.0.tar.gz.s

Prior to the release, new Remote Modules should be enabled in the Doxygen build's configuration.


  • Run CMake in the binary build and enable BUILD_DOXYGEN
  • Do Configure and Generate in CMake
  • Go to the binary directory
  • Type "make Documentation"
  • Move into the directory Utilities/ ( cd Utilities/ )
  • Rename the Doxygen directory as DoxygenInsightToolkit-3.4.0 (of course with the appropriate release number)
  • Tar it with the command: tar -cf DoxygenInsightToolkit-3.4.0.tar DoxygenInsightToolkit-3.4.0
  • Compress it with the command: gzip -9 DoxygenInsightToolkit-3.4.0.tar

Historical note: Before ITK 3.8, The documentation used to be generated in a directory called Documentation/Doxygen.

  • In Public do:
    • Copy documentation to: /projects/Insight/Doxygen
      • Create a subdirectory Insight34-doxygen/Documentation/Doxygen
      • The final directory will look like: /projects/Insight/Doxygen/Insight34-doxygen/Documentation/Doxygen
      • and at that level copy the "html" directory and the InsightToolkit.tag file.
    • Create symbolic link at: /projects/Insight/WWW/InsightWeb
    • (DEPRECATED - last release 4.1) Create symbolic link at: /projects/Insight/WWW/InsightDocuments/Web

Copy the files to the FTP directory in public.kitware.com

 scp   InsightData-4.12.0.tar.gz                  kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightData-4.12.0.tar.xz                  kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightData-4.12.0.zip                     kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightToolkit-4.12.0.tar.gz               kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightToolkit-4.12.0.tar.xz               kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightToolkit-4.12.0.zip                  kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightApplications-4.12.0.tar.gz          kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightApplications-4.12.0.zip             kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightDoxygenDocHtml-4.12.0.tar.gz        kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightDoxygenDocTag-4.12.0.tar.gz         kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightDoxygenDocXml-4.12.0.tar.gz         kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   ItkSoftwareGuide.pdf                       kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightSoftwareGuide-Book1-4.12.0.pdf      kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightSoftwareGuide-Book2-4.12.0.pdf      kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightSoftwareGuideHtml-4.12.0.tar.gz     kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightWikiExamples-4.12.0.tar.gz          kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 scp   InsightWikiExamples-4.12.0.zip             kitware@public:/projects/Insight/WWW/InsightWeb/files/v4.12
 ssh kitware@public
 cd /projects/Insight/WWW/InsightWeb
 rm ItkSoftwareGuide.pdf
 ln -s files/v4.12/ItkSoftwareGuide.pdf ItkSoftwareGuide.pdf

Copy the files to SourceForge

This is to be done only by

  • Ken Martin at Kitware
  • Brad King at Kitware
  • Matt McCormick at Kitware
  • Francois Budin at Kitware
  • Brad Lowekamp at NLM

Using The New (2010) Interface

Go to this page

  https://sourceforge.net/downloads/itk/itk/

and provide user name and password

Then

  • Use the "Add Folder" button to create a folder for the release.
  • Click on the folder to open it
  • Use the "Add File" button to upload files. The interface allows you to select multiple files for simultaneous upload.

After uploading, make sure to check the hashes on the uploads. These can be shown with the "(i)" button next to the file.

Large files, like the Doxygen HTML tarball, need to be uploaded with scp, a la:

 scp InsightDoxygenDocHtml-4.7.0.tar.gz mmmccormic@frs.sourceforge.net:/home/frs/project/itk/itk/4.7/InsightDoxygenDocHtml-4.7.0.tar.gz

Update the HTML Download page

Contact Communications at Kitware in order to

Update the HTML Documentation page

Documentation.htm

Contact Communications at Kitware in order to update the page:

  http://www.itk.org/ITK/help/documentation.html

The content should be updated to point to the Doxygen documentation of the current release

Update the Release Notes in the Wiki

Add entry for next planned release

Delete the old entry and add a new entry in the scheduled releases page

Update the Releases page

Add the "What's New" and "What's Changed" entries to the Releases page.

Update "What's New in Release x.x" Wiki Page

Update this web-page with the e-mail sent to the ITK mailing indicating the notable changes and other important information about the release.

Update "What has Changed since previous release"

From a Linux system, cd into an ITK Git directory and run

 git shortlog --topo-order --no-merges v4.0.0..v4.1.0

Delete the KWRobot time stamp commits.

Update Insight Journal (deprecated)

Contact Zack and request to do the following:

  • Install new ITK version in the Insight Journal testing environment
  • Update IJMacros.txt: Add the just released version of ITK

Update JIRA issue tracker

  • Create a new version to make possible for users to report bug pertaining to that specific ITK release
    • Create the next release target milestone with Administration -> ITK -> Versions -> Add
    • Release the current release milestone with Agile -> Classic ... -> Right click the release on the left -> Release

Further Testing

The purpose of this testing is to replicate the experience that a user may have when trying the new release.

This means that a number of ITK developers should download the tarballs or do Git checkouts with the release tag, and build the toolkit in as many configuration as possible.

Notes

  • ITK minor releases (patch) do not have a tagged release candidate.



ITK: [Welcome | Site Map]