====== 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 [[https://github.com/mantisbt/mantisbt|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)

For reference, you may also read the [[http://anonscm.debian.org/viewvc/collab-maint/ext-maint/mantis/trunk/debian/TestingNewRelease?view=log|test plan for new Mantis releases in Debian]].


==== Localization ====

  * Post on the [[mantisbt-lang@lists.sourceforge.net|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. <code>
$ cd /path/to/mantisbt
$ php -q /path/to/check_lineterm.php -c </code>
  * If any files are found with non-UNIX-style line-endings, fix them with <code>
$ php -q /path/to/check_lineterm.php -c <filename>
</code>
  * Alternatively, check and fix all files in one go with the following command <code>
$ php -q /path/to/check_lineterm.php -a <filename>
</code>
  * Review and commit the changes


===== Preparing the Release =====

==== Localization ====

  * Contact the [[http://translatewiki.net|TranslateWiki]] team (Siebrand) to request an update of tranlations

==== Repository Preparation ====

  * Remove references to any debug statements 
  * Update CREDITS file.
    * If necessary, [[mantisbt:mailmap|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 <code>
$ update-credits.sh
</code>
    * If needed, make any additional changes manually
  * Update the version number in core/constant_inc.php.
  * Commit the changes.



===== Cutting the Release =====

  * 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** <code>
$ git checkout master-M.N
$ VERSION=M.N.P
$ git tag -s release-$VERSION -m "Stable release $VERSION"
</code> Note: If this fails, see below for tag signing troubleshooting
    * For **development releases** (e.g. alpha, beta, release candidates) <code>
$ git checkout master
$ VERSION=M.N.P
$ git tag -s release-$VERSION -m "Development release $VERSION"
</code>

  * Push the tag to Github <code>
$ git push origin release-$VERSION
</code>

  * In case we are starting a new stable branch, also create it using the format "master-M.N": <code>
$ git branch master-M.N master
$ git push origin master-M.N
</code>



**Troubleshooting failure to sign tags**

Signing the tag fails if GIT cannot map the user with the gpg key, as in the example below <code>
$ 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
</code>

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 <code>
$ git tag -u <key-id> release-$VERSION -m "Stable release $VERSION"
</code>
  - Update git config settings
    * Define which key to use <code>
$ git config [--global] user.signingkey <key-id>
</code>
    * 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:
<code>
$ /build/buildrelease-repo.py --fresh --docbook --ref release-$VERSION --clean /path/to/output
</code>

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.




===== Updating mantisbt.org =====

==== Bugtracker ====

  * Update Versions
    - Go to the [[https://mantisbt.org/bugs/manage_proj_edit_page.php?project_id=1#versions|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 <WRAP important 90%>
The [[mantisbt:plugins:sourceintegration]] 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).
</WRAP>
      * 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)
      * 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
    - 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

==== Nightly builds ====

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.

<code>$ sudo /srv/mantisbt-tools/nightly-builds.sh</code>


==== 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: <code>
$ cd /srv/www
$ ../mantisbt-tools/update-trackers.sh bugs demo
</code>
  * 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: <code>
$ ../mantisbt-tools/update-trackers.sh -c <Tag or Commit sha> bugs
</code>
Please refer to the script's help and comments for further details on command-line options.

=== Manual process ===

Also refer to MantisBT Administration Guide [[http://www.mantisbt.org/docs/master-1.3.x/en-US/Admin_Guide/html-desktop/#admin.install.upgrade|upgrade section]].

**Upgrade Official Bug Tracker Instance**

  * Make sure you are running as root (sudo bash)
  * Update the code from git <code>
$ cd /srv/www/bugs/
$ git checkout master-1.3.x
$ git pull --rebase
$ git checkout bugs
$ git rebase master-1.3.x
</code>
  * 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 [[http://sourceforge.net/projects/mantisbt/files/|SourceForge]] <WRAP info>
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.
</WRAP>
    * manually via SourceForge's File Manager web interface, or
    * with rsync (//USERNAME// is your SourceForge user ID) <code>
$ rsync -vP --rsh=ssh /path/to/output/* USERNAME@frs.sourceforge.net:/home/frs/project/mantisbt/mantis-stable/$VERSION
</code>
  * 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.

==== Notifications ====

  * Blog: Post an announcement
  * [[https://matrix.to/#/#mantisbt_mantisbt:gitter.im|Gitter]]: Post an announcement
  * [[https://phpc.social/@mantisbt|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.

===== Prepare for next release =====

==== Bump the version number ====

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 [[https://mantisbt.org/builds.php|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