ITK/How to make a Release: Difference between revisions
Line 103: | Line 103: | ||
Pre-populate the store with the contents of the 'InsightData' tarballs from a previous release. | Pre-populate the store with the contents of the 'InsightData' tarballs from a previous release. | ||
Then, configure ITK, enable ''BUILD_TESTING'' and ''BUILD_EXAMPLES'', and build the ''ITKData'' target | Then, from the ITK build directory, configure ITK, enable ''BUILD_TESTING'' and ''BUILD_EXAMPLES'', and build the ''ITKData'' target | ||
make ITKData | make ITKData | ||
Line 109: | Line 109: | ||
This will download new testing data since the previous release. | This will download new testing data since the previous release. | ||
Next, run the script: | Next, run the script from within the ITK source directory: | ||
./Utilities/Maintenance/ContentLinkSynchronization.sh | ./Utilities/Maintenance/ContentLinkSynchronization.sh |
Revision as of 01:52, 3 November 2016
How To Make an ITK Release
This page describes the sequence of steps required for making an ITK release
General steps
- Create tag (with GPG signature) for release. Do not forget to update ITK revision number in CMakeLists.txt.
- Create release notes:
git shortlog --no-merges v4.10.0..release
- 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 www.itk.org. Verify that links work!
- 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, 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
Before tagging the ITKApps repository, make a commit that bumps the superbuild ITK tag to this release.
git tag -m "ITK 4.5.0 Applications" -s v4.5.0-apps 2f012cb96715b59c63c9ee66022f398e236b04bd
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.
Mark the release as resolved on the issue tracker
Schedule the next release, and update the Release Schedule page.
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.
Then, from the ITK build directory, configure ITK, enable BUILD_TESTING and BUILD_EXAMPLES, and 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
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/ArchiveTestingData.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.
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/
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
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 InsightSoftwareGuide-Book* 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
ITK Sphinx Examples
Bump the Superbuild ITK version in Superbuild/External-ITK.cmake.
Rendered versions 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.7.0
wget 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 at the bottom of the Doxygen HTML pages.
- 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
- Create symbolic link at: /projects/Insight/WWW/InsightDocuments/Web
- Copy documentation to: /projects/Insight/Doxygen
Copy the files to the FTP directory in public.kitware.com
scp InsightToolkit-2.4.0.tar.gz kitware@public:/projects/Insight/WWW/InsightDocuments/Web/files/v2.4 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 InsightSoftwareGuide-4.5.0.pdf kitware@public:/projects/Insight/WWW/InsightDocuments/Web/files/v4.5 ssh kitware@public cd /projects/Insight/WWW/InsightWeb rm ItkSoftwareGuide.pdf ln -s files/v4.5/ItkSoftwareGuide.pdf ItkSoftwareGuide.pdf
Copy the files to SourceForge
This is to be done only by
- Ken Martin at Kitware
- Luis Ibanez at Kitware
- Brad King at Kitware
- Matt McCormick 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 Doxyget 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 Download HTML page: http://www.itk.org/ITK/resources/software.html
- Produce a press release
- Update http://itk.org/ItkSoftwareGuide.pdf
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
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 releasef
- 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.