Overview

The release manager role in MXNet means you are responsible for a few different things:

1. Preparing for release candidates:
   1. cutting a release branch
   2. informing the community of timing
   3. working with component leads to clean up backlog
   4. making code changes in that branch with necessary version updates
2. Running the voting process for a release:
   1. creating release candidates using automated tooling
   2. calling votes and triaging issues
3. Finalizing and posting a release:
   1. updating the MXNet website
   2. writing release notes
   3. announcing the release

Preparing MXNet for Release

The main step towards preparing a release is to create a release branch. This is done via standard Git branching mechanism and should be announced to the community once the branch is created. A Jenkins jobs for the release branch has to be setup once the branch is in created and test results must be published on the mailing list (consult Ly Nguyen for help with this).

Next, ensure that all MXNet versions are correct in the code base on the release branch (TODO see this example commit). You should grep through the codebase to find all instances of the version string. Some known places to change are:

• TODO

Finally, update CHANGES.txt with this script in the MXNet repository. CHANGES.txt captures all the patches that have made it into this release candidate since the last release.

TODO

$ export MXNET_HOME=<your Spark home>
$ cd mxnet
# Update release versions
$ vim dev/create-release/generate-changelist.py
$ dev/create-release/generate-changelist.py

This produces a CHANGES.txt.new that should be a superset of the existing CHANGES.txt. Replace the old CHANGES.txt with the new one (TODO see this example commit).

Branch creation announcement template

To: dev@mxnet.apache.org
Subject: New release branch 0.10.0

Hello MXNet developers and friends,

As promised, we now have a release branch for 0.10.0 release (with 0.10.0.0
as the version).
Trunk has been bumped to 0.10.1.0-SNAPSHOT.

I'll be going over the github issues to move every non-blocker from this release to
the next release.

From this point, most changes should go to trunk.
*Blockers (existing and new that we discover while testing the release) will be double-committed. 
*Please discuss with your reviewer whether your PR should go to trunk or to trunk+release so they can merge accordingly.
*Please help us test the release! *

Thanks!

$RM

Cutting a Release Candidate

If this is not the first RC, then make sure that all issues on github related to previous RC have been solved since the last RC are marked as FIXED in this release version.

• A possible protocol for this is to mark such issues as FIXED in next maintenance release. For example if you are cutting RC for 1.0.2, mark such issues as FIXED in 1.0.3.
• When cutting new RC, find all the issues that are marked as FIXED for next maintenance release, and change them to the current release.
• Verify from gitlog whether they are actually making it in the new RC or not.

The process of cutting a release candidate has been automated via Jenkins. There are Jenkins jobs that can tag a release candidate and create various packages based on that candidate. The recommended process is to ask the previous release manager to walk you through the Jenkins jobs or consult with Ly Nguyen.

Call a Vote on the Release Candidate

The release voting takes place on the Apache MXNet developers list (the PMC is voting). Look at past voting threads to see how this proceeds. The email should follow this format.

• Make a shortened link to the full list of github issues using https://s.apache.org/
• If possible, attach a draft of the release notes with the email
• Make sure the voting closing time is in UTC format. Use this script to generate it - TODO
• Make sure the email is in text format and the links are correct
• RM must have gpg keys with the public key publicly available to validate the authenticity of the Apache MXNet release: If you haven't set up gpg key, set up one using 4096 bit RSA (http://www.apache.org/dev/release-signing.html). Make sure that your public key is uploaded to one of the public servers (http://www.apache.org/dev/release-signing.html#keyserver). Also, add your public key to https://github.com/apache/mxnet-site/blob/asf-site/KEYS

Voting email template

To: dev@mxnet.apache.org
Subject: [VOTE] Release plan - MXNET 0.11

We are starting the process to prepare for MXNET $release release. I have created release plan ($link) to cover the tasks under this release.

If you have any tasks in progress and would like to include it in this release, please follow the process to do so.

Feel free to comment on the github if you have any comments/suggestions.

Thanks,
$RM

Once the vote is done, you should also send out a summary email with the totals using the template below.

To: dev@mxnet.apache.org
Subject: [RESULTS] [VOTE] Release MXNet version 0.10.0.0

This vote passes with 7 +1 votes (3 bindings) and no 0 or -1 votes.

+1 votes
PMC Members:
* $Name
* $Name 
* $Name

Committers:
* $Name
* $Name

Community:
* $Name
* $Name

0 votes
* No votes

-1 votes
* No votes

Vote thread:
https://lists.apache.org/list.html?commits@mxnet.apache.org/

I'll continue with the release process and the release announcement will follow in the next few days.

$RM

Finalize the Release

Be Careful!

THIS STEP IS IRREVERSIBLE so make sure you selected the correct staging repository. Once you move the artifacts into the release folder, they cannot be removed.

After the vote passes, create the release. To upload the binaries, you have to first upload them to the dev directory in the Apache Distribution repo, and then move the binaries from dev directory to release directory. This “moving” is the only way you can add stuff to the actual release directory.

TODO UPDATED WITH MXNET SCRIPTS
# Checkout the Spark directory in Apache distribution SVN "dev" repo
$ svn co https://dist.apache.org/repos/dist/dev/spark/
  
# Make directory for this RC in the above directory
mkdir spark-1.1.1-rc2
 
# Download the voted binaries and add them to the directory
$ scp andrewor14@people.apache.org:~/public_html/spark-1.1.1-rc2/* spark-1.1.1-rc2
 
# NOTE: Remove any binaries you don’t want to publish
# E.g. never push MapR and *without-hive artifacts to apache
$ rm spark-1.1.1-rc2/*mapr*
$ rm spark-1.1.1-rc2/*without-hive*
$ svn add spark-1.1.1-rc2
$ svn commit -m "Add spark-1.1.1-rc2" --username "andrewor14"
  
# Move the sub-directory in "dev" to the
# corresponding directory in "release"
$ export SVN_EDITOR=vim
$ svn mv https://dist.apache.org/repos/dist/dev/spark/spark-1.1.1-rc2 https://dist.apache.org/repos/dist/release/spark/spark-1.1.1

Verify that the resources are present in https://www.apache.org/dist/mxnet. It may take a while for them to be visible. This will be mirrored throughout the Apache network. There are a few remaining steps.

Remove Old Releases from Mirror Network

MXNet always keeps two releases in the mirror network: the most recent release on the current and previous branches. To delete older versions simply use TODO. The TODO file in the website ... must also be updated to reflect the changes. For instance, the two releases should be 1.1.1 and 1.0.2, but not 1.1.1 and 1.1.0.

TODO

$ svn rm https://dist.apache.org/repos/dist/release/spark/spark-1.1.0

Update the MXNet Apache Repository

Check out the tagged commit for the release candidate that passed and apply the correct version tag.

TODO
$ git checkout v1.1.1-rc2 # the RC that passed
$ git tag v1.1.1
$ git push apache v1.1.1
 
# Verify that the tag has been applied correctly
# If so, remove the old tag
$ git push apache :v1.1.1-rc2
$ git tag -d v1.1.1-rc2

Next, update remaining version numbers in the release branch. If you are doing a patch release, see the similar commit made after the previous release in that branch. For example, for branch 1.0, see this example commit.

In general, the rules are as follows:

• grep through the repository to find such occurrences
• References to the version just released. Upgrade them to next release version. If it is not a documentation related version (e.g. inside mxnet/docs/ or inside ...), add -SNAPSHOT to the end.
• References to the next version. Ensure these already have -SNAPSHOT.

Update the MXNet Website

The website repository is located at TODO. Ensure the docs were generated with the PRODUCTION=1 environment variable - TODO

# TODO Add instructions how to build docs and update the website

Next, update the rest of the MXNet. See how the previous releases are documented. In particular, have a look at the changes to the *.md files in this commit.

TODO

# Add git cmds to update 

Then, create the release notes. The contributors list can be automatically generated through TODO this script. It accepts the tag that corresponds to the current release and another tag that corresponds to the previous (not including maintenance release). For instance, if you are releasing MXNet 1.2.0, set the current tag to v1.2.0-rc2 and the previous tag to v1.1.0. Once you have generated the initial contributors list, it is highly likely that there will be warnings about author names not being properly translated. To fix this, run this other script, which fetches potential replacements from Github.

Additionally, if you wish to give more specific credit for developers of larger patches, you may use the the following commands to identify large patches. Extra care must be taken to make sure commits from previous releases are not counted since git cannot easily associate commits that were back ported into different branches.

TODO
 
# TODO Update to reflect MXNet process
$ cd release-spark/dev/create-release
# Set RELEASE_TAG and PREVIOUS_RELEASE_TAG
$ vim generate-contributors.py
# Generate initial contributors list, likely with warnings
$ ./generate-contributors.py
# Set JIRA_USERNAME, JIRA_PASSWORD, and GITHUB_API_TOKEN
$ vim release-spark/dev/translate-contributors.py
# Translate names generated in the previous step, reading from known_translations if necessary
$ ./translate-contributors.py

# Determine PR numbers closed only in the new release
$ git log v1.1.1 | grep "Closes #" | cut -d " " -f 5,6 | grep Closes | sort > closed_1.1.1
$ git log v1.1.0 | grep "Closes #" | cut -d " " -f 5,6 | grep Closes | sort > closed_1.1.0
$ diff --new-line-format="" --unchanged-line-format="" closed_1.1.1 closed_1.1.0 > diff.txt
 
# Grep expression with all new patches
$ EXPR=$(cat diff.txt | awk '{ print "\\("$1" "$2" \\)"; }' | tr "\n" "|" | sed -e "s/|/\\\|/g" | sed "s/\\\|$//")
 
# Contributor list
$ git shortlog v1.1.1 --grep "$EXPR" > contrib.txt
 
# Large patch list (300+ lines)
$ git log v1.1.1 --grep "$expr" --shortstat --oneline | grep -B 1 -e "[3-9][0-9][0-9] insert" -e "[1-9][1-9][1-9][1-9] insert" | grep SPARK > large-patches.txt

Then, update the downloads page, and then the main page with a news item.

Create an Announcement

Once everything is working (website docs, website changes) create an announcement on the website and then send an e-mail to the mailing list. Enjoy an adult beverage of your choice, and congratulations on making a MXNet release.