wiki:ReleaseProcedure

Version 58 (modified by Peter, 11 years ago) (diff)

use scp to upload files

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, e.g. 0.3, or 1.0):

  1. Check that YAT_LT_VERSION_INFO is set correcly otherwise update following line in m4/version.m4
    m4_define([YAT_LT_VERSION_INFO], [c:r:a])
    
  2. Add a line in NEWS
    See the end for copyrights and conditions.
    
    +yat A.B.x series from http://dev.thep.lu.se/yat/svn/branches/A.B-stable
    +
    Version A.B (released NOT YET)
    
    commit the changes with svn ci -m "bumping version to A.B.1pre"

  3. Update copyright statements with command:
    svndigest --copyright --no-report -v
    
    Examine the updates and commit changes with svn ci -m "updating copyright statements". For this step svndigest is obviously needed.

  4. Create a new minor branch using a one liner like
    svn copy http://dev.thep.lu.se/yat/svn/trunk \
        http://dev.thep.lu.se/yat/svn/branches/A.B-stable \
        -m "New minor version A.B branch"
    
  5. Check out a WC from the newly created branch
    svn co http://dev.thep.lu.se/yat/svn/branches/A.B-stable yat-A.B
    
  6. Copy the svndigest cache from trunk WC to branch WC
    svndigest-copy-cache -v -r /path/to/yat-trunk -t /path/to/yat-A.B
    
    which needs svndigest 0.8 or newer.

  7. Prepare the trunk for the next minor release

    1. Update version number in m4/version.m4. Locate and change the below lines
      m4_define([MINOR_VERSION], [B+1])
      m4_define([YAT_LT_VERSION_INFO], [c+1:0:0])
      
    2. Add an entry in NEWS
      version A.[B+1] (released NOT YET)
      
      The date is set when version A.[B+1] is released.

    3. Commit changes to the repository, svn ci -m "Bumping VERSION to A.[B+1]pre"

  8. When someone with access to documentation site has time available, they will upgrade to the new branch. This person is usually not the release manager, so please send a reminder.

Rolling a minor release

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

    1. Update version number in m4/version.m4. Locate and change the below line
      m4_define([DEV_BUILD], [false])
      
    2. Update the interface version number in m4/version.m4. Locate and set the version in the below line
      m4_define([YAT_LT_VERSION_INFO], [c:r:a])
      
      appropriately. Refer to the interface version list in m4/version.m4 to figure out the settings of c, r, and a. c should increase with 1 if the interface has changed. If the interface is changed, r should be set to zero and a should be set to reflect backward compatibility level of this version. If interface was not changed just increase r with 1. See m4/version.m4 and the libtool manual for details.

    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 people's 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. Commit changes to the repository, svn ci -m "Preparing release A.B"

  2. Update copyright statements with command:
    svndigest --copyright --no-report -v
    
    Examine the updates and commit changes with svn ci -m "updating copyright statements". For this step svndigest is obviously needed.

  3. 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:

    Run
    make all
    make release
    
    Fix potential problems.

  4. 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/yat/svn/branches/A.B-stable \
        http://dev.thep.lu.se/yat/svn/tags/A.B \
        -m "Tagging version A.B"
    
  5. Upload yat-A.B.tar.gz and md5 file to sourceforge using scp like
    scp yat-A.B.tar.gz yat-A.B.tar.gz.MD5 USER,libyat@frs.sourceforge.net:/home/frs/project/l/li/libyat/.
    
  6. Update SubversionCheckout and WikiStart

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

    4. On WikiStart update links [source:tags/A.B/NEWS NEWS] and [source:branches/A.B-stable/README README].

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

  8. Update the version list in Trac using the trac-admin tool.
  9. Merge the minor release into the trunk. To avoid confusion and minimize the risk of loosing fixes, this step is only performed by the Merge Master.

    1. Go to a pristine trunk WC
      cd /path/to/yat-trunk/
      svn update
      svn status -q
      
    2. Merge changes into trunk.
      svn merge http://dev.thep.lu.se/yat/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. Typically changes in m4/version.m4 are problematic so check this file extra carefully.

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

    1. Update version number in m4/version.m4. Locate and change the below lines
      m4_define([PATCH_VERSION], [1])
      m4_define([DEV_BUILD], [true])
      
    2. Add an entry in NEWS
      version A.B.1 (released NOT YET)
      
      The date is set when version A.B.1 is released.

    3. Commit changes to the repository, svn ci -m "Bumping VERSION to A.B.1"

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) (configure.ac), acknowledge contributions (THANKS), update NEWS.

    1. Update the release version number in m4/version.m4. Locate and change the below line
      m4_define([DEV_BUILD], [false])
      
      Confirm YAT_LT_VERSION_INFO and add an entry in list of versions.

    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.

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

  2. Update copyright statements with command:
    svndigest --copyright --no-report
    
    Examine the updates and commit changes with svn ci -m "updating copyright statements". For this step svndigest is obviously needed.

  3. 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:

    Run
    make all
    make release
    
    Fix potential problems.

  4. 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/yat/svn/branches/A.B-stable \
        http://dev.thep.lu.se/yat/svn/tags/A.B.C \
        -m "Tagging version A.B.C"
    
  5. Upload yat-A.B.C.tar.gz and md5 file to sourceforge using scp like
    scp yat-A.B.C.tar.gz yat-A.B.C.tar.gz.MD5 USER,libyat@frs.sourceforge.net:/home/frs/project/l/li/libyat/.
    
  6. Update SubversionCheckout and WikiStart

    1. In section yat 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/yat/svn/tags/A.B.C yat-A.B.C
      
      svn switch http://dev.thep.lu.se/yat/svn/tags/A.B.C
      
    2. In section yat stable update link to [milestone:A.B.[C+1] A.B.[C+1]].

    3. On WikiStart update reference to explicit latest version number, and [source:tags/A.B/NEWS NEWS].

  7. Close the milestone associated with the release, replace head with appropriate revision in log link, set diff to 'diff:tags/A.B.[C-1]//tags/A.B.C/'. Create a log link, 'log:branches/A.B-stable@TAG-REVISION:head', and diff, 'diff:tags/A.B.C//branches/A.B-stable/', in milestone associated with next patch release.

  8. Update the version list in Trac using the trac-admin tool. Remember to set the date.

  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. cd to a pristine trunk WC
      cd /path/to/yat-trunk/
      svn update
      svn status -q
      
    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
      svn merge http://dev.thep.lu.se/yat/svn/branches/0.6-stable
      
    3. Resolve all conflicts. Run tests and perform all other appropriate tests to make sure that the merge does not create havoc. Typically changes in m4/version.m4 are problematic so check this file extra carefully.

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

    1. Update version number in m4/version.m4. Locate and change the below lines
      m4_define([PATCH_VERSION], [C+1])
      m4_define([DEV_BUILD], [true])
      
    2. Update the interface version number in m4/version.m4. Locate and change the below line
      m4_define([YAT_LT_VERSION_INFO], [c:r+1:a])
      
      i.e., only raise the revision number since the interface will not change. See the libtool manual for details.

    3. Add an entry in NEWS
      version A.B.[C+1] (released DATE)
      
      The date is set when version A.B.[C+1] is released.

    4. Commit changes to the repository, svn ci -m "Bumping VERSION to A.B.[C+1]"