Release Manager Checklists

Introduction

Release cycle initialization

  • In boost super-project branch develop, change version number in:
    • root/index.html (2 places; H2 and Release History link)
    • root/Jamroot (1 place)
    • root/more/getting_started/detail/release-variables.rst (4 places)
    • In root/more/getting_started, run b2.
    • Inspect results.
  • Create a pull request for config:
    • include/boost/version.hpp (2 places) - Note that BOOST_LIB_VERSION should not include the patch version if it's zero.
  • Commit version number and Getting Started doc changes:
    • Commit develop, push.
    • Merge develop to master (wait for config?).
    • Commit master, push.
  • Update the Google calendar as described in ReleaseSchedule so that it is always several releases ahead. This is really important; it causes endless trouble if the calendar isn't updated.

  • Verify the root/index.html, root/boost/version.hpp, root/Jamroot release numbers are correct and agree.

  • Verify via jamboost@… that b2 pre-built executables up-to-date.

  • Create a placeholder for release information at: website/public_html/live/feed/history/, for example for boost 1.39.0:
    git clone git@github.com:boostorg/website.git live-website
    cd live-website
    cp feed/templates/boost_x_xx_x.qbk feed/history/boost_1_60_0.qbk
    
    # Edit the version number (in two places) in the new entry
    
    python site-tools/update.py
    git add feed/history/boost_1_60_0.qbk
    git add users/history/version_1_60_0.html
    git commit -a -m "Stub release notes for 1.60.0"
    git push
    

Monitoring Release Progress

  • Monitor regression tests ( http://boost.sourceforge.net/regression-logs) to verify that errors are actively being reduced or accounted for on key platforms and compilers.
    • Boost errors are being actively worked on by library maintainers.
    • Compiler or standard library errors are at least identified, and preferably reported to the supplier.
    • No errors remain uninvestigated or unclassified.

  • Monitor the developer and user mailing lists to verify that all posted patches are being applied, rejected, or otherwise dealt with.

  • Monitor the developer and user mailing lists, and outstanding tickets, to verify that all posted bug reports are being investigated, fixed, rejected, or otherwise dealt with.

  • Monitor SVN commits to verify that all the expected and/or promised content actually gets committed. Try to get developers to avoid last minute commits of major changes.

New Library Checklist

Create GitHub Repository

Before a release manager creates a  boostorg GitHub repository for the new library, the release manager should send an email to developer:

The release manager performs two steps to add the new library to  GitHub:

  • Do one of two things:
    • If the library already has a GitHub repository,  transfer the repository to boostorg. Getting the maintainer to transfer into the organization is a bit awkward. So it might be best to first transfer the repo to an admin, who can then transfer it into the organization and set up the team.
    • If the library does not already have a GitHub repository,  Create the library's repository. Note: the release manager creates a repository that is empty except for a readme file. The library's developer is responsible for creating the library's contents.
  • Go into the repo settings, and make sure the owner has admin permissions.

Add library as a submodule on boost develop branch

Before a release manager adds the library as a submodule on the boost super-project develop branch, the release manager should verify the library is ready to start regression testing:

  • The critical elements of the library xxx directory structure are in place:
    • libs/xxx/include/boost/xxx has the header files.
    • libs/xxx/test has a Jamfile.v2, and b2 works. Tests don't have to pass, but the Jamfile needs to be in good enough shape that it will not break regression testing.
    • If it is a compiled library, libs/xxx/build has a Jamfile.v2 in in good enough shape that it will not break regression testing.
    • The directory structure in general is reasonably complete and boost-like.
  • Run inspect and verify the report is not a total disaster. It does not have to be totally clean, but it should be clean enough to indicate the developer has the general idea of what is required.

Add library as a submodule on boost master branch

Before a release manager adds the library as a submodule on the boost super-project master branch, the release manager should verify:

  • The formal review manager is satisfied any requirements for inclusion set by the formal review have been met.
  • The repo contains an index.html file with either the main docs or a redirection to the main docs.
  • `meta/libraries.json` is present in the repo and contents look reasonable.
  • The primary docs pages meet Boost requirements and guidelines. Don't leave this until too late; it has turned up lots of issues in the past.
  • Inspection report is clean.
  • Regression on develop tests are reasonably clean.

After a new library is merged into master, the release manager should verify:

  • Doc builds, if any, are running properly.
  • Release branch inspection report is clean.
  • Release branch regression tests are reasonably clean or marked up.

Before the beta test, the release managers should ensure that:

Beta Release

Verify branch and release index.html have been updated with the number of new libraries.

If it hasn't been done recently, run, then check and commit:

cd %BOOST_RELEASE%
cd tools/regression
2release tools/regression [--dry-run]
cd tools/release
2release tools/release [--dry-run]

Follow the Build Distribution packages, Releases, and Subversion Beta and Release Tags procedures below as for regular releases.

This is probably a good time to pester people about updating website/public_html/live/feed/history/boost_n_nn_0.qbk

Between Beta and Release

See ReleasePractices/PostBetaMerges

Build Distribution Packages

  • Make sure that the documentation is up to date. In particular, when the documentation source files get updated, the docs for the website need to be regenerated and merged to release.
  • If it hasn't already been done, run a snapshot using tools/release/snapshot.bat.

  • Build the distribution packages using tools/release/build_release_packages.bat.
    cd <snapshot-directory>
    %BOOST_TRUNK%\tools\release\build_release_packages boost_X_XX_X_beta1 >build_packages.log 2>&1
    
  • Unpack the distribution package for your local operating system, and verify build works OK. No point in posting a release candidate already known to fail!
    cd <boost-root>
    bootstrap
    .\b2 >build.log 2>&1
    
  • Upload distribution packages to snapshot ftp site.

Releases

  • Important: Release team must have signed off on packages. Ignoring this in the past has led to mistakes!

  • Create a directory on SourceForge?:
    • login
    • Files
    • Click on "boost" folder to list current sub-directories | Add folder | Folder name: 1.46.0.beta.1 | Create
  • Upload release packages:
    • Click on folder just added.
    • Add README file from trunk/tools/release/README
    • Add File. Repeat for each distro file. Although the interface allows selecting multiple files, error recovery is much easier if files are uploaded one-by-one. For each file in the snapshot directory to be uploaded, select the file and hit "Upload". NOTE WELL: Spurious timeout error messages may appear. Ignore them. The MD5 checksum verification trumps error messages.
  • Verify MD5 checksums:
    • Use file "info" to get MD5 checksums; put them in a file, n.nn.n.md5, in the snapshot directory. It should look like this:
      da33b65571cbbbd9c667dc6458e16a86 *boost_1_46_1.zip
      b0a8949a3cd452c1bcb6cea8380cc01d *boost_1_46_1.7z
      7375679575f4c8db605d426fc721d506 *boost_1_46_1.tar.bz2
      341e5d993b19d099bf1a548495ea91ec *boost_1_46_1.tar.gz
      
    • Windows only: run: chg n.nn.n.md5 "\r" "" strip "\r" or md5sum can't find files
    • Run: md5sum -c -w <n.nn.n.md5 should list all files, status OK
  • Complete SourceForge? release process:
    • login
    • Project Admin | File Manager
    • Verify files are present and in the correct directory.
    • Click Files (on upper menu bar), and check "Newest Files" entries are correct. (There may be a delay before labels appear)
    • Go back to this release's folder, and click on the 'i' icon to the right of the 'tar.bz2' file, select 'default download' for everything but windows, and click on 'save'. Once that has finished (it can be slow, you might want to open the page in another window), click on the 'i' icon to the right of the 'zip' file and select windows, and click on 'save' again.
  • Tag the release in git. Make sure the correct versions of the super project and submodules are checked out, and then do something like:
    git tag boost-1.58.0
    git submodule foreach 'git tag boost-1.58.0'
    git push origin boost-1.58.0
    git submodule foreach 'git push origin boost-1.58.0'
    
  • If this is a final release, rather than a beta release, let the webmaster (currently Daniel) know the release is ready to go live. Wait until the site is updated before posting the release message.

  • Post a message announcing the release.


Copyright Beman Dawes 2001, 2008

Distributed under the Boost Software License, Version 1.0. (See http://www.boost.org/LICENSE_1_0.txt)