Process to follow for creating new CREDO releases

General release configuration description

CREDO follows a fairly standard open source project release naming convention, where releases are named MAJOR.MINOR.MICRO, e.g. 0.1.3, where MAJOR is the major release, MINOR is the micro release, and MICRO are small releases with incremental updates/bugfixes.

CREDO follows a typical ‘named branches’ and tags strategy for managing these versions and releases in the Mercurial repository:

• There are ‘named branches’ for major release lines, e.g. credo-0.1
• Actual micro releases are tags along these branches of when the code was released, e.g. credo-0.1.1
• That way, patches/fixes can be ported across to the release branch lines from the ‘default’ trunk branch if necessary.

Release Process Steps

Follow these steps when creating a CREDO release:

1. Review the README.txt file, and if necessary make any updates (eg updating the list of contributors, or web links).

2. Create/switch to the release branch:

   • In the cases where the release branch doesn’t exist, you need to create it by using a “hg branch BRANCHNAME” command.
   • In cases where it does exist, just switch to the branch using “hg update -C BRANCHNAME”.

3. Create a CHANGELOG file for the release:

   • use Mercurial command to select all changes since last release tag made, and save to a file in the changelogs subdirectory. E.g. for getting changes between the 0.1.2 and the tip (upcoming 0.1.3 release):

     hg log -v -r credo-0.1.2:tip > changelogs/CHANGELOG-0_1_3

     Note

     Save this to file in the “changelogs” subdirectory named CHANGELOG-X-Y-Z, where X, Y, and Z are the major, minor and micro revisions.

   • Edit the file you just created, and add an appropriate header, e.g.

     ===================================================================
     Mercurial commits made during CREDO development from 0.1.2 to 0.1.3
     ===================================================================

   • Remember to hg add the file, you will commit it later.

   Note

   We would be interested in any better method for assembling changelogs in Python mercurial code that helps select changes of real interest.

4. Update the doc/credo-whatsnew.rst file:

   • Add a new section header for the new release following on the pattern of previous ones, and add a short summary of key new features in bullet point form.

     The CHANGELOG file you just created in the previous step should be helpful in doing this, as well as trac tickets and roadmaps.

     Where appropriate use Sphinx links in this summary to help users find new features.

5. Update the release number in the documentation conf.py file:

   This will look something like the following, just edit as appropriate:

   # The short X.Y version.
   version = '0.1'
   # The full version, including alpha/beta/rc tags.
   release = '0.1.2'
   

6. At this stage you should commit all the changes made above to the release branch, and also tag the release code:

   hg commit
   hg tag TAGNAME
   hg push

7. Create a source tarball of this release:

   Make sure you are in the root directory of your CREDO checkout and type:

   hg archive -t tgz ../credo-X.Y.Z.tar.gz

   ... where X.Y.Z is the release number, e.g. 0.1.3. This will create the tarball in the parent directory.

8. Update links and upload the just-created tarball in the release table at https://www.mcc.monash.edu.au/trac/AuScopeEngineering/wiki/CREDO

9. TODO: in future we should perhaps have a process to create a copy of the documentation of each release (PDF/html) and put online.