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
   • Push access to the Github repository
   • GnuPG installed with a GPG key setup
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

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

• 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.

• 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 .

• 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.

• 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

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

• 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.

• 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

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 ?

• 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

• 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

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.

• 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.

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.

• Upload the release to Source Forge via the File Manager web interface
• Release through the SF.net mechanism.
  • The release name should be “1.2.x” (e.g. 1.2.9).
  • Put the release in the appropriate package based on whether it is a stable or a development release.
  • Release candidates and alphas 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.
  • for README file exclude from stats. [1]
• Post news on Mantis SF project area.

[1] [dregad] The Build release script does not generate a README file - maybe this is obsolete

• 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.