RELEASE.txt - how to create a CMF release

  Most of the work necessary to create a CMF release is done by the script
  'slurp_release.py', which can always be found in the root of the CMF 
  package on the Subversion trunk. The script will svn export the CMF 
  package, build the tarballs, and upload them and the respective READMEs 
  to the CMF area on www.zope.org.

  Before running 'slurp_release.py' the respective branch needs to be cleaned
  up and tagged properly. 
  
  **Important note**: Always run all CMF unit tests before even thinking of
  cutting a new release.


  **Naming conventions**

    In order to stay consistent the following naming conventions for CMF
    versions and for Subversion tags used to tag releases should be used,
    demonstrated with the help of a notional 1.8.4 release:

      - CMF beta versions are '1.8.4-beta' and '1.8.4-beta2' for the second
        beta. The same is true for alpha releases if one is desired.
        '1.8.4-alpha2' follows '1.8.4-alpha'. Alpha releases should only
        be necessary for the first release off a new release branch. The final
        version would then be '1.8.4'

      - Subversion tags are the same as the version number. So our CMF 1.8.4
        release would be tagged as '1.8.4'. '1.8.4-beta2' would indicate the 
        second beta release.

      - Branch tags in Subversion look like '1.8' for the branch that
        would yield e.g. version 1.8.4. In essence, the branch tag only
        contains the major release number.


  **Preparing the branch**

    To release version '1.8.4-beta2' off the '1.8' branch the following
    steps are needed. It is assumed the release manager is using the tip
    of the '1.8' Subversion branch to make these changes:

      - At the top of 'CHANGES.txt', enter the current date as YYYY/MM/DD
        in parentheses next to the CMF version number.

      - Find all 'version.txt' files throughout the CMF package and adjust 
        the version number, in this case 'CMF-1.8.4-beta2'.

      - Check all DEPENDENCIES.txt files and ensure the lowest common
        denominator for packages not being shipped as part of the CMF tarball 
        is correctly mentioned in INSTALL.txt

      - Check these changes into the Subversion repository

      - Create the Subversion tag by svn copying the head of the release
        branch to the tag in the tags repository directory.

      - Even though checking into a tag is an insidious thing to do, it is
        OK for changing SVN Externals definitions. Specifically, a CMF
        release tag should not contain SVN Externals pointing to branches.
        If needed, a tag on the external package should be cut and then
        the external definition adjusted to point to the tag.


  **Creating and publishing the release**

    Now that the Subversion repository is prepared the files need to be put onto
    zope.org. First of all, the Software Release object needs to be created.
    Go to http://www.zope.org/Products/CMF and create a Software Release 
    from the Folder Contents view:

      - Name CMF-1.8.4-beta2

      - Version 1.8.4-beta2

      - Maturity value depends on status: beta releases are 'development'

      - License ZPL

      - Info URL '/Products/CMF/CMF-1.8.4-beta2/README.txt'

      - License URL '/Resources/License/ZPL-2.1'

      - Changes URL '/Products/CMF/CMF-1.8.4-beta2/CHANGES.txt'

      - Installation URL '/Products/CMF/CMF-1.8.4-beta2/INSTALL.txt'

    Make sure to publish this Software Release. Due to a problem with the 
    zope.org site at the time of this writing, you need to specify an
    effective date on the publishing form if you want the item to show up on
    the zope.org front page. Just choose the current data using the date
    picker widget.

    With Subversion and zope.org preparations done the 'slurp_release.py' 
    script will do the remaining work. You run it with version ID 
    (like '1.8.4-beta2') as parameter::

      slurp_release.py [options] version_id

    slurp_release can be run from anywhere, it does not depend on your 
    Subversion sandbox because it will create its own. Without any options 
    it will complete the whole procedure including upload to the zope.org site. 
    Use 'slurp_release.py --help' to find out more.

    Once 'slurp_release.py' has completed the upload step you need to visit
    the uploaded files on zope.org and make sure they get published on the 
    site. See the note about specifying an effective date above.


  **Announcing the release**

    An announcement email should go out to zope-announce@zope.org, 
    zope-cmf@zope.org and zope@zope.org. Also, a NewsItem for the release
    should be created on the zope.org site. The existing News Items inside
    http://www.zope.org/Products/CMF can be used as models for your
    announcement.

