Mantis Release Process

Prerequisites

To execute the steps described in this document, the operator must have the following in terms of access rights and setup

  1. To test before the release
    • A local machine with MantisBT
  2. To prepare the release
  3. To update mantisbt.org
    • root access on the server
    • administrator access on the bugtracker
  4. To publish the release
    • Ability to post on mantisbt-announce and mantisbt-dev mailing lists, Twitter and blog
    • Admin access to Sourceforge

Planning the Release

This activity should start about 2 weeks before the planned release date.

General Readiness

  • Review the issues in bugtracker to make sure there are no critical issues that need to be included in the release.
  • Check with the developers (via the mailing list and/or IRC) that there are no pending issues for the release.

Testing

  • General testing.
    • At a minimum, each page that has been touched should be visited, and all links and buttons checked for functionality.
  • Test the changes in the release, specially the latest one applied.
  • Test upgrading previous releases.
    • Where the database schema has been changed, both a new install and an upgrade of a reasonably populated install should be tried.

For major releases, a regression of all features is very desirable. Testing should cover:

  • multiple database platforms
  • integration with other tools (e.g., wiki, source code management)
  • optional features (e.g., graphs)

The test process for Mantis in the Debian distro can be found at http://svn.debian.org/wsvn/collab-maint/ext-maint/mantis/trunk/debian/TestingNewRelease?op=file&rev=0&sc=0 .

Localization

  • Post on the Localization mailing list to request translation updates from contributors
  • Run /admin/test_langs.php to detect any syntax errors in the localization files.

File Cleanup

  • Run the Lines Termination test script on all the files to make sure the line terminations are UNIX style.
    $ cd /path/to/mantisbt
    $ php -q /path/to/check_lineterm.php -c 
  • If any files are found with non-UNIX-style line-endings, fix them with
    $ php -q /path/to/check_lineterm.php -c <filename>
    
  • Alternatively, check and fix all files in one go with the following command
    $ php -q /path/to/check_lineterm.php -a <filename>
    
  • Review and commit the changes

Preparing the Release

Localization

  • Contact the TranslateWiki team (Siebrand) to request an update of tranlations

Repository Preparation

  • Remove references to any debug statements
  • Update CREDITS file.
    • If necessary, update the .mailmap file at the repository’s root, so that commit made by the same person under different names and/or e-mail addresses are properly aggregated (refer to git shortlog man page for details)
    • Run the script to update the Contributor’s list
      $ update-credits.sh
      
    • If needed, make any additional changes manually
  • Update the version number in core/constant_inc.php.
  • Update doc/RELEASE to include the release notes.
  • Commit the changes.

Cutting the Release

  • Create an annotated tag in Git, the tag should be formatted as “release-1.x.x”
    • For stable releases: GPG-signed tag
      $ git checkout master-1.M.x
      $ VERSION=1.M.N
      $ git tag -s release-$VERSION -m "Stable release $VERSION"
      

      Note: If this fails, see below for tag signing troubleshooting

    • For development releases: unsigned, annotated tag
      $ git checkout master
      $ VERSION=1.M.N
      $ git tag -a release-$VERSION -m "Development release $VERSION"
      
  • Push the tag to Github
    $ git push origin release-$VERSION
    
  • In case we are starting a new stable branch, also create it using the format “master-1.x.x”:
    $ git branch master-1.x.x master
    $ git push origin master-1.x.x
    

Troubleshooting failure to sign tags

Signing the tag fails if GIT cannot map the user with the gpg key, as in the example below

$ git tag -s release-$VERSION -m "Stable release $VERSION"
gpg: skipped "Your Name <name@example.com>": secret key not available
gpg: signing failed: secret key not available
error: gpg failed to sign the data
error: unable to sign the tag

For automatic key mapping, git config user.name and git config user.email must exactly match the gpg key’s uid. If they don’t, there are 2 options:

  1. Manually specify the key when signing the tag
    $ git tag -u <key-id> release-$VERSION -m "Stable release $VERSION"
    
  2. Update git config settings
    • Define which key to use
      $ git config [--global] user.signingkey <key-id>
      
    • Try to sign the tag again

Packaging the Release

Generate release tarballs using the buildrelease-repo.py script found in the mantisbt-tools.git repository:

$ /path/to/buildrelease-repo.py --fresh --docbook --ref release-$VERSION /path/to/output /path/to/repo

This will create a .zip and .tar.gz tarball of the release, and create a .digest file for each tarball with md5 and sha1 hashes, all in the /path/to/output directory specified in the command. The –docbook option will automatically build single-file versions of the manuals into the tarball’s /doc directory.

[dregad] the script also creates ‘.asc’ files, which are not documented in SourceForge section - what to do with them ?

Updating mantisbt.org

Bugtracker

  • Update Versions
    1. Go to the Manage Projects page for the mantisbt project
    2. Update the version being released (1.M.x):
      • Rename it to 1.M.N
      • Update the “Date Order” field to the actual release date
      • Copy-paste the text from the release notes into the “Description” field, update as appropriate
      • Tick the “Released” box
    3. Create a new 1.M.x version
      • Set the “Date Order” field to a future date
      • Make sure the “Released” box is not ticked
  • Update issues
    1. Go to the View Issues page
    2. Close all resolved issues that are fixed in the version being released
      • Set a new filter: Status = resolved, Fixed in Version = 1.M.N
      • Review listed issues, update them as needed (in particular, check that Resolution = fixed)
      • Tick the Select all checkbox
      • Select Close and click OK
      • Click the Close Issues button
      • Repeat until the filter is empty
    3. Carry open issues still targeted to 1.M.N over to the new 1.M.x version
      • Set a new filter: Hide Status = closed (And Above), Target Version = 1.M.N
      • Tick the Select all checkbox
      • Select Update Target Version and click OK
      • Select 1.M.x from the list and click the Update Target Version button
      • Repeat until the filter is empty

Website

  • Update the latest version
    • Edit main website’s config file /srv/www/main/config_inc.php
    • Update $g_latest_version_stable or $g_latest_version_dev as appropriate, to match the version being released

Deployment

This section describes how to deploy the new release on the official and demo bugtrackers on http://mantisbt.org.

The task can either be performed by executing a script, or manually (aka the hard way); please refer to the relevant section below.

Automated process (Update script)

  • Execute the following steps, running as root, to update both trackers:
    $ cd /srv/www
    $ ../mantisbt-tools/update-trackers.sh bugs demo
    
  • Carefully review the script’s output for any errors, correct them as necessary and re-run the script if needed

Note: the script is also able to update a single tracker, or to target a specific commit instead of the current upstream branch’s HEAD, as follows:

$ ../mantisbt-tools/update-trackers.sh -c <Tag or Commit sha> bugs

Please refer to the script’s help and comments for further details on command-line options.

Manual process

Also refer to MantisBT Administration Guide upgrade section.

Upgrade Official Bug Tracker Instance

  • Make sure you are running as root (sudo bash)
  • Update the code from git
    $ cd /srv/www/bugs/
    $ git checkout master-1.2.x
    $ git pull --rebase
    $ git checkout bugs
    $ git rebase master-1.2.x
    
  • Upgrade the database if needed (admin/admin_upgrade.php).
  • Run admin/admin_check.php and resolve any issues.
  • Login and do simple testing.

Upgrade Demo Instance

  • Make sure you are running as root (sudo bash)
  • Update the code from git
    $ cd /srv/www/demo/
    $ git checkout master-1.2.x
    $ git pull --rebase
    $ git checkout demo
    $ git rebase master-1.2.x
    
  • Upgrade the database if needed (admin/admin_upgrade.php).
  • Run admin/admin_check.php and resolve any issues.
  • Login and do simple testing.

Publishing the Release

Source Forge

  • Upload the release to SourceForge via the File Manager web interface
  • Release through the SF.net mechanism.
    • The release name should be “1.2.x” (e.g. 1.2.17).
    • Put the release in the appropriate package based on whether it is a stable or a development release.
    • Release candidates, alphas and betas are “development” releases.
  • Download the release off SF.net and verify correctness.
  • Click the “i” next to the files under the folder and do the following actions:
    • for digests, exclude them from stats.
    • for zip make it default for all platforms.

Notifications

  • Blog: Post an announcement
  • Twitter: announce the release via mantisbt twitter account.
  • IRC: Change the title of #mantishelp to announce the new release and encourage people to use it.
  • Forums: Announce the release on the Announcements forum.
  • Mailing Lists: Send a message to mantisbt-announce / mantisbt-dev to announce the new release and encourage users to upgrade. Include a link to the version changelog.
 
Logged in as: anonymous
mantisbt/release_process.txt · Last modified: 2014/03/04 01:00 by vboctor