This is an old revision of the document!
Table of Contents
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
- To test before the release
- A local machine with MantisBT
- To prepare the release
- Push access to the Github repository
- GnuPG installed with a GPG key setup
- To update mantisbt.org
- root access on the server
- administrator access on the bugtracker
- 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. (for 1.2.x releases - not applicable to 1.3.x+)
- 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:
- Manually specify the key when signing the tag
$ git tag -u <key-id> release-$VERSION -m "Stable release $VERSION"
- 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
- Go to the Manage Projects page for the mantisbt project
- 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
- 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
- Go to the View Issues page
- 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
- 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.