wiki:ReleaseProcedure

Version 52 (modified by Peter Johansson, 12 years ago) (diff)

added a missing "commit changes"

Contents

  1. Publishing a release
    1. Minor release procedure
      1. Creating a release branch
      2. Rolling a minor release
    2. Patch release procedure

Publishing a release

These instructions cover how to release minor and patch releases in a project that uses trac/subversion for revision control and project management. How to release major releases is not covered yet since we have not done that (with the exception of the first release). Release numbering follows the normal convention of major.minor.patch and the APR (see http://apr.apache.org/versioning.html) guidelines for releases are used.

The main development is performed in the trunk branch of the repository. A new release branch is created for each minor release from the trunk and patch releases are snapshots of the minor release branch. This implies that patch work is performed in the minor release branch, and changes made release branch is transferred to the trunk every time a new patch release is made. Remember, patch work should be limited to bug fixes and important fixes only leaving development of new features and designs to the trunk branch.

Releases should only be performed by an appointed member of the team, the Release Manager, and merges should be performed by a Merge Manager. Of course, one team member can be both managers, thus becoming the Release and Merge Manager.

Minor release procedure

This section describes what to do when publishing a minor release.

Creating a release branch

Once people agree that a new release branch should be made, the Release Manager creates it with the following procedure (substitute A.B with the version you are preparing):

  1. Update copyright statements with commands
    make && make check
    ./bin/svndigest --copyright --no-report -v
    
    Examine the updates and commit changes with svn ci -m "updating copyright statements"

  2. Create a new release branch using a one liner like
    svn copy http://dev.thep.lu.se/svndigest/svn/trunk \
        http://dev.thep.lu.se/svndigest/svn/branches/A.B-stable \
        -m "New minor version A.B branch"
    
  3. Prepare the trunk for the next minor release

    1. Update version number in build_support/version.m4. Locate and change the below line
      m4_define([MINOR_VERSION], [B+1])
      
  4. Add an entry in NEWS
    version A.[B+1] (released DATE)
    
    The date is set when version A.[B+1] is released.

  5. Add an entry in ChangeLog
    version A.[B+1]:
    	- http://dev.thep.lu.se/svndigest/log/branches/A.B-stable?rev=HEAD&stop_rev=M+1
    	- http://dev.thep.lu.se/svndigest/query?milestone=A.[B+1]&order=id
    
  6. Update version number in README. Locate and change line
    This directory contains the A.[B+1] release of svndigest` 
    
  7. Commit changes to the repository, svn ci -m "Changes for future release A.[B+1]"

Rolling a minor release

For this procedure to work as expected, no other developers should commit to the repository, during the process of release. Communicate with co-developers!

  1. Make sure that all commits are performed into to the trunk, such as bumping version number(s) (version.m4), acknowledge contributions (THANKS), update files NEWS and ChangeLog.

  2. Update version number in version.m4. Locate and change the below line
    m4_define([SVNDIGEST_DEV_BUILD], [false])
    
  3. Update THANKS. Remember, ego and vanity is the currency of open source projects. Well, there are other reasons for open source projects but THANKS is for boosting peoples' ego.

  4. Set the date for the new release in NEWS
    version A.B (released 26 June 2007)
    
    Make sure that the items in NEWS cover the new features of the release.

  5. Finalize the links to trac in ChangeLog
    version A.B:
    	- http://dev.thep.lu.se/svndigest/log/trunk?rev=N&stop_rev=M
    	- http://dev.thep.lu.se/svndigest/query?milestone=A.B&order=id
    
    where M should be current HEAD+2 (1 or 2 more commits are needed before release).

  6. Commit changes to the repository
    svn ci -m "Preparing release A.B"
    
  7. Update copyright statements with commands
    autoreconf -m
    make check
    ./bin/svndigest --copyright --no-report -v
    
    Examine the updates and commit changes with svn ci -m "updating copyright statements"

  8. Needless to say, make sure that the program is in a state to be released; make sure that all the tests pass, test the distribution package, and perform all other release tests you think is appropriate:

    Remove all unversioned files using
    svn-clean
    
    Check that remove was complete and that wc is up to date
    svn status -u
    
    which should display nothing. Build and test the package
    ./bootstrap && ./configure && make && make check && make distcheck
    
    If everything is ok, attach the new package to the DownloadPage, else start over.

  9. Create a tag, but first check that you are synchronized with repository
    svn status -q -u
    
    and then create a tag using a one liner like
    svn copy http://dev.thep.lu.se/svndigest/svn/branches/A.B-stable \
        http://dev.thep.lu.se/svndigest/svn/tags/A.B \
        -m "Tagging version A.B"
    
  10. Update the version list in Trac using the trac-admin tool. Remember to set the date

  11. Update DownloadPage and WikiStart

    1. Update the section Latest stable release to reflect the new version, that is

      • Change the version number

      • Update the package link to the new version

      • Update link to NEWS file to source:tags/A.B/NEWS

    2. In section svndigest latest release update link to [source:tags/A.B/NEWS NEWS] and modify the svn commands to
      svn checkout http://dev.thep.lu.se/svndigest/svn/tags/A.B svndigest-A.B
      
      svn switch http://dev.thep.lu.se/svndigest/svn/tags/A.B
      
    3. In section svndigest stable update link to [milestone:"svndigest A.B.1" A.B.1] and modify the svn commands to
      svn checkout http://dev.thep.lu.se/svndigest/svn/branches/A.B-stable svndigest-A.B
      
      svn switch http://dev.thep.lu.se/svndigest/svn/branches/A.B-stable
      
    4. In section svndigest devel update link to [milestone:"svndigest A.B+1" A.B+1].

    5. On WikiStart update links [source:tags/A.B/doc/readme.txt Manual], [source:tags/A.B/NEWS NEWS], [source:tags/A.B/README README], and also make sure that list of features is up to date.

  12. Merge the release into the trunk. To avoid confusion and minimize the risk of loosing fixes, this step is only performed by the Merge Master.

    1. Checkout a pristine version of the trunk.
      svn checkout http://dev.thep.lu.se/svndigest/svn/trunk trunk_merge
      
    2. Merge changes in release branch since the fork into the trunk
      cd trunk_merge
      svn merge http://dev.thep.lu.se/svndigest/svn/branches/A.B-stable@[fork] \
                http://dev.thep.lu.se/svndigest/svn/branches/A.B-stable
      
    3. Resolve all conflicts. Run tests and perform all other appropriate tests to make sure that the merge does not create havoc.

    4. Commit changes to the trunk branch.
      svn commit -m "Merged branch A.B-stable to the trunk. Delta A.B - A.B@[fork]"
      
  13. Prepare the minor branch for the first patch release

    1. Go to release branch directory
      cd path/to/svndigest-stable-branch/
      
    2. Update version number in version.m4. Locate and change the below line
      m4_define([PATCH_VERSION], [1])
      m4_define([SVNDIGEST_DEV_BUILD], [true])
      
    3. Add an entry in NEWS
      version A.B.1 (released DATE)
      
      The date is set when version A.B.1 is released.

    4. Add an entry in ChangeLog
version A.B.1:
	- http://dev.thep.lu.se/svndigest/log/branches/stable-A.B?rev=[M+1]&stop_rev=HEAD


	- http://dev.thep.lu.se/svndigest/query?milestone=A.B.1&order=id
  1. Commit changes to the repository, svn ci -m "Changes for future release A.B.1"

  1. Close the milestone associated with the release and replace head with appropriate revision. Add a new milestone as needed (with log link).

Patch release procedure

This section describes what to do when publishing a patch release A.B.C.

  1. Make sure that all commits are performed into to the branch, such as bumping version number(s) (version.m4), acknowledge contributions (THANKS), update files NEWS and ChangeLog.

    1. Update version number in configure.ac. Locate and change the below line
      m4_define([SVNDIGEST_DEV_BUILD], [false])
      
    2. Update THANKS.

    3. Set the date for the new release in NEWS
      version A.B.C (released 27 June 2007)
      
      Make sure that the items in NEWS cover all important bug fixes of the release.

  2. Finalize the links to trac in ChangeLog
    version A.B.C:
    	- http://dev.thep.lu.se/svndigest/log/branches/A.B-stable?rev=N&stop_rev=M
    	- http://dev.thep.lu.se/svndigest/query?milestone=A.B.C&order=id
    
    where N is given by
    $ svn update
    N-2
    
    and M should have been set at previous release.

  3. Commit changes to the repository, svn ci -m "Preparing release A.B.C"

  4. Update copyright statements with commands

    autoreconf -m
    make check
    ./bin/svndigest --copyright --no-report -v
    
    Examine the updates and commit changes with svn ci -m "updating copyright statements".

  5. Needless to say, make sure that the program is in a state to be released; make sure that all the tests pass, test the distribution package, and perform all other release tests you think is appropriate:

    Remove all unversioned files using
    svn-clean
    
    Check that remove was complete and that wc is up to date
    svn status -u
    
    which should display nothing. Build and test the package
    ./bootstrap && ./configure && make && make check && make distcheck
    
    If everything is ok, attach the new package to the DownloadPage, else start over.

  6. Create a tag using a one liner like
    svn copy http://dev.thep.lu.se/svndigest/svn/branches/A.B-stable \
        http://dev.thep.lu.se/svndigest/svn/tags/A.B.C \
        -m "Tagging version A.B.C"
    
  7. Update the version list in Trac using the trac-admin tool. Remember to set the date

  8. Update DownloadPage and WikiStart

    1. Update the section Latest stable release to reflect the new version, that is

      • Change the version number

      • Update the package link to the new version

      • Update link to NEWS file to source:tags/A.B.C/NEWS

    2. In section svndigest latest release update link to [source:tags/A.B.C/NEWS NEWS] and modify the svn commands to
      svn checkout http://dev.thep.lu.se/svndigest/svn/tags/A.B.C svndigest-A.B.C
      
      svn switch http://dev.thep.lu.se/svndigest/svn/tags/A.B.C
      
    3. In section svndigest stable update link to [milestone:"svndigest A.B.[C+1]" A.B.[C+1]].

    4. On WikiStart update reference to explicit latest version number, and links [source:tags/A.B/doc/readme.txt Manual], [source:tags/A.B/NEWS NEWS], and [source:tags/A.B/INSTALL Install].

  9. Merge the patch release into the trunk. To avoid confusion and minimize the risk of loosing fixes, this step is only performed by the Merge Master.

    1. Checkout a pristine version of the trunk.
      svn checkout http://dev.thep.lu.se/svndigest/svn/trunk trunk_merge
      
    2. Merge changes into trunk. In this example the diffence between a minor release tag and the first patch release tag is merged into the trunk WC
      cd trunk_merge
      svn merge http://dev.thep.lu.se/svndigest/svn/tags/A.B \
                http://dev.thep.lu.se/svndigest/svn/tags/A.B.1
      
    3. Resolve all conflicts. Run tests and perform all other appropriate tests to make sure that the merge does not create havoc. Note, changes in version.m4 should typically not be merged into trunk.

    4. Commit changes to the trunk branch.
      svn commit -m "Merged patch release A.B.1 to the trunk. Delta A.B.1 - A.B"
      
  10. Prepare the minor branch for the next patch release

    1. Update version number in configure.ac. Locate and change the below line
      m4_define([PATCH_VERSION], [C+1])
      m4_define([SVNDIGEST_DEV_BUILD], [true])
      
    2. Add an entry in NEWS
      version A.B.[C+1] (released DATE)
      
      The date is set when version A.B.[C+1] is released.

    3. Add an entry in ChangeLog
      version A.B.[C+1]:
      	- http://dev.thep.lu.se/svndigest/log/branches/A.B-stable?rev=HEAD&stop_rev=[M+1]
      	- http://dev.thep.lu.se/svndigest/query?milestone=A.B.[C+1]&order=id
      
    4. Commit changes to the repository, svn ci -m "Changes for future release A.B.[C+1]"

  11. Close the milestone associated with the release and replace head with appropriate revision in log link. Add a new milestone as needed (with a log link).