Mantis Release Process

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)

For reference, you may also read the test plan for new Mantis releases in Debian.

• 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, so that commit made by the same person under different names and/or e-mail addresses are properly aggregated
  • 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.
• Commit the changes.

• Create an annotated, GPG-signed tag in Git; the tag should be formatted as release-M.N.P (e.g. 2.25.4)
  
  
  • For stable releases

    $ git checkout master-M.N
    $ VERSION=M.N.P
    $ git tag -s release-$VERSION -m "Stable release $VERSION"

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

  • For development releases (e.g. alpha, beta, release candidates)

    $ git checkout master
    $ VERSION=M.N.P
    $ git tag -s 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-M.N”:

  $ git branch master-M.N master
  $ git push origin master-M.N

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:

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

This will create the following files in the /path/to/output directory specified in the command.

• a .zip and .tar.gz tarball of the release
• a .digest file for each tarball with md5 and, sha* hashes
• an ASCII-armored GPG signature file for each tarball (with .asc extension)

The –docbook option will automatically build single-file versions of the manuals into the tarball's /doc directory.

• 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

       The Source Control Integration plugin relies on this date to automatically set the Fixed in version field when processing commits referencing issues for resolution (i.e. Fixes #xxx).

       For this to work properly, it is important that the version targeted by the master branch always has the most recent date. Adjust it if necessary (e.g. when cutting a patch release).

     • 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)
     • Private security issues should be made public
     • 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

When releasing a new major (X+1.0.0) or minor (X.Y+1.0) release, the nightly builds script must be updated so that the files are generated for the appropriate branches.

• Edit the script /srv/mantisbt-tools/nightly-builds.sh
• Update the branches variable to specify the names of all the repository branches for which a nightly build is required

To make the change permanent, the file should be committed to the mantisbt/mantisbt-tools repository.

If desired, the script may be executed manually at this point. Note that it normally does not produce any output; check the log file at /var/log/nightly-builds.log for errors.

$ sudo /srv/mantisbt-tools/nightly-builds.sh

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.3.x
  $ git pull --rebase
  $ git checkout bugs
  $ git rebase master-1.3.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 SourceForge

  Put the files in the appropriate directory, based on the release type: Stable releases go to the mantis-stable; Alpha, Beta and Release candidates go in mantis-development.

  Create a sub-directory for the version, matching it's number e.g. 2.0.0-beta.1, 2.23.0, 2.24.4.

  • manually via SourceForge's File Manager web interface, or
  • with rsync (USERNAME is your SourceForge user ID)

    $ rsync -vP --rsh=ssh /path/to/output/* USERNAME@frs.sourceforge.net:/home/frs/project/mantisbt/mantis-stable/$VERSION

• Download the release off SF.net and verify correctness.
• Click the (i) icon next to the files under the folder and do the following actions:
  • for digests, exclude them from stats.
  • In case of a stable release, make the zip file the default for all platforms.

• Blog: Post an announcement
• Gitter: Post an announcement
• Mastodon: Post an announcement

The notifications below require accounts that only vboctor has access to…

• Twitter: announce the release via mantisbt twitter account.
• Update mailing list based on official bug tracker users since users can now signup to our bugtracker to get such announcements.
• Use sendgrid to send out the announcement email.

The MantisBT version constant must be increased to reflect the current state of the development branch.

This ensures that people running Mantis from the GIT repository are not led to believe they are working with an official release, and allows the Nightly builds to reference the proper version in the zip/tarball file name.

• Edit core/constants_inc.php
• Update MANTIS_VERSION by incrementing the version number as appropriate:
  • Major version: x+1.0.0-dev
  • Minor version: x.y+1.0-dev
  • Patch version: x.y.z+1-dev
• Commit and push the modified file