Release procedure

Release numbering

  • Version number is in README and this is pulled dynamically into the configuration json document.
  • We have an unstable branch called merge
    • Code gets merged into here - that's a difficult process to get right, so we like to have a special branch that is occassionally broken for this
  • We have a development freeze branch called release candidate
    • The idea is that we can insulate a release from any changes while we make last tweaks and run a final set of tests before pushing out as a release
  • We have a release branch called release
    • I try to get it so release never breaks

Basically, we don't have any of

  • enough users;
  • enough developers;
  • a sufficiently mature code base;
  • a sufficiently sophisticated workflow;

to make it worth doing anything more sophisticated.

0.0.1--0.0.2--0.0.3------------------> Release branch
   ^       ^        ^     \    
  /       /        /       \
 /       /        /         \ merge down
-------------------> Release \
       ^         ^   candidate\  
      /         /              \
     /         /                \
-------------------> Merge branch\
     ^          ^                 \
    / merge    /                   \
   /          /                    \/
-------------------> Feature branches

Once we have core code in place, we can review things and see how we're coming on. For version numbering

0.0.x is a biweekly/occasional release of the trunk
0.1.x is marks a feature set complete (e.g. we can now reconstruct x detector)
1.x.y marks a significant feature set complete (e.g. we can now reconstruct all detectors)

Release Procedure

We plan to make a minor release every 2 weeks (tie in to MAUS dev meetings). For version 1.2.3:

Check the test server

Check on Jenkins that the following branches are stable (blue or green):
  • MAUS_per_commit_third_party
  • MAUS_per_commit_third_party_brunel_mice_host
  • MAUS_per_commit_third_party_brunel_6
  • MAUS_per_commit_third_party_heplnm070
  • MAUS_build_and_unit_test
  • MAUS_full_install
  • MAUS_geometry_download
  • MAUS_integration_tests
  • MAUS_StepI_Unpacker

Update MICE mine

Update a few things in the MAUS section of MICE Mine:
  • Make a new version in Settings > Versions tab
  • Look for issues that are Closed but have Future MAUS Release version. Assign them to the new version
  • Lock the version in Settings > Versions tab

Prepare the release candidate

  1. Merge from lp:maus/merge to lp:maus/release-candidate
    • Make a note of any changes to third_party things that indicate a rebuild required of third_party libraries

In lp:maus/release-candidate - few things to update:

  1. Check for any defunct third party libraries and remove them
  2. Check RELEASENOTES. Update for any new commits since the last release.
    • If any third_party/bash/*.bash scripts have changed or been added, mention this - users will need to rebuild if they are upgrading from an old version.
  3. in README edit file version number (at top of file) to give new MAUS version 1.2.3
    • First line is read at run time to be the version number
    • First line is checked in tests to follow this format, so really must follow the pattern
  4. Update src/common_cpp/Utils/VersionNumber.hh
  5. Build MAUS
  6. Update the third_party libraries listed in ReleaseNotes; then try running tests locally - does it work?
    • Be prepared to trip up on third_party_libraries download - this uses version number to get the right tarball...
    • ssh to and then link third_party_libraries tarball from previous version directory to the new version directory (i.e. mimic the third party tarball)
      • The third_parties tarball is in directory /www/maus/MAUS_release_version_X.Y.Z; redirects to index.html in this directory
  7. Run style tests (or pull from test server). Move tmp/pylint.json to tests/style/ref-pylint.json
  8. Check that third_party/build_all.bash has ${MAUS_ROOT_DIR}/third_party/bash/40python_extras.bash -gi NOT -cgi i.e. no -c option

Create and deploy the server files

  1. Run ${MAUS_ROOT_DIR}/tests/ (you may have latex issues...)
  2. Compile doc/workbook/MausWorkBook.tex
  3. Copy the documentation from tmp/server_build/<version>/maus_user_guide.pdf to doc/
  4. Commit changes into the release candidate
  5. Copy ${MAUS_ROOT_DIR}/tmp/server_build/<version> to
    • Note that this will put a new copy of third_party_libraries_incl_python.tar.gz on the web page - which is required to get the new version of MAUS working
  6. Run the test server build ( Wait a while. Now's a good time to have a cup of tea or maybe a slice of cake. I find reading a paper quite soothing.
  7. Copy the install.log from the test server build to<version>
  1. Then merge into the release branch lp:maus/release with commit message MAUS-vX.Y.Z. From release branch
    1. Remove dead tags from the branch (everything that doesn't conform to MAUS-vX.Y.Z)
    2. bzr tag MAUS-v1.2.3; bzr tag MAUS-v1.2
      1. If there's a pre-existing tag for MAUS-v1.2, force the retag with bzr tag --force MAUS-v1.2
    3. move the file to the server
      1. bzr export MAUS-v1.2.3.tar.gz; md5sum MAUS-v1.2.3.tar.gz >& MAUS-v1.2.3.tar.gz.md5
        (Rogers: this makes a big file called packs in .bzr/repository - does this do anything? Why is there a .bzr file at all? - looks like it is somehow a changelog with diffs stored in it for recent changes...)
      2. copy in heplnm072:/www/maus/MAUS_release_version_1.2.3/
    4. check the md5
      1. md5sum -c MAUS-v1.2.3.tar.gz.md5 
      2. Add a gpg app armor file:
         gpg --armor --sign --detach-sig MAUS-v1.2.3.tar.gz 
        This creates a file called MAUS-v1.2.3.tar.gz.asc.
  2. Make the final changes to the server set up
    1. Copy the source tarball, md5 and asc to<version>. Check the md5 is okay.
    2. Edit to reflect change
    3. Check for broken links at
    4. Update latest_release softlink to reflect change and check that MAUS Documentation points at the latest release.
      1. ln -sfn MAUS_release_version_<version> MAUS_latest_version

Release on Launchpad

  1. Go the MAUS launchpad site and login (you will need to be a member of the maus-maintainers team):
  2. Under "Series and Milestones" click on "trunk" (not "merge", "release", or "release-candidate"!)
  3. Under "Milestones and releases" click "Create milestone":
    1. Name: v1.2.3
    2. Date: the current date
    3. Tags: MAUS-v1.2.3
    4. Summary: Copy the release notes here
    5. Create the milestone
      Create a milestone
  4. Find the new milestone from the list and click "Release now"
    1. Date: the current date
    2. Release notes: copy the release notes again
    3. Click "Create release"
  5. Upload the release tarball MAUS-v1.2.3.tar.gz (as "MAUS-v1.2.3 release source tarball") and the corresponding asc file when prompted

Last things

  1. Merge release branch back into the merge branch if appropriate
  2. Merge release branch back into other common branches
  3. Let things stew for a bit - then announce the release
  4. Onto deployment

Note also that I would like to do something with physics validation plots.

See also

Updated by Franchini, Paolo about 5 years ago ยท 150 revisions