Overview

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

1. Preparing for release candidates:
   1. informing the community of timing
   2. prepare release notes (bug fixes, features added)
   3. making code changes with necessary version updates
   4. cutting a release candidate
2. Running the voting process for a release:
   1. calling votes and triaging issues, revote if necessary
3. Finalizing and posting a release:
   1. marking & publishing the official release
   2. updating the MXNet website
   3. announcing the release

Pre-requisites:

1. You are a current project committer
2. You’ve gained access to configure build jobs at builds.apache.org as a part of the jobsadmin group (ask a PMC mentor to add you)

1. Preparing the Release Candidate:

Step 1.1. Prepare Release Notes (bug fixes, features added)

Draft release notes which should include the list of new features and bug fixes, along with limitations, known issues, credits, etc.

• All problems/fixes in release notes MUST have the PR link and a possible workaround if any
• new features must be added to the readme/tutorial. 

#!/bin/bash
# to get a list of commits since <date>
git log --pretty=format:"%h - %cn, %cd : %s" --no-merges --since="2017-09-01" > commits.txt
 
# To get a list of committers since <date>
git shortlog -sne --since="10 Aug 2017"

Step 1.2. Inform the Community of timing

After every release, the community should decide on a list of features to deliver for the following release. When the clear target date for a release has been estimated, the release manager should inform the community of the release schedule. All features which the community wishes to include in the release should be merged and tested successfully before the date of the first release candidate. The first release candidate should be on a commit which passed builds from at least 3 days before cutting the release candidate. This will make the release manager's job easier. Below is a template for the information:

To: dev@mxnet.apache.org

Subject: Release plan - MXNET 0.11

I am starting the process to prepare for MXNET $release release. I have drafted release notes ($link) to cover the tasks under this release.

A release candidate will be cut on $utc_date and voting will commence $utc_date_vote0 - $utc_date_vote1. If you have any additional features in progress and would like to include it in this release, please assure they have been merged by $utc_date-72 comment so I may update the release notes.

Feel free to add any other comments/suggestions.

Thanks,

$RM

Step 1.3. Make code changes with necessary version updates

At least 3 days prior to cutting the first release candidate, bump up the version number and address other changes that the release depends on.

1. Bump up the version number. An example can be followed here: https://github.com/apache/incubator-mxnet/pull/6462, update https://github.com/apache/incubator-mxnet/blob/master/setup-utils/install-mxnet-osx-python.sh#L36
   More recent example - https://github.com/apache/incubator-mxnet/pull/8567
   make sure no broken/non-existing links are added to the master branch.
2. Update NEWS and README. An example can be followed here: https://github.com/apache/incubator-mxnet/pull/6471

3. Create a RSA GPG key of length 4096, upload it to the public server, and add it to the KEYS file (do this process once for each release manager): https://github.com/apache/incubator-mxnet/blob/master/KEYS & https://dist.apache.org/repos/dist/dev/incubator/mxnet/KEYS See more detailed instructions on creating the key here: https://www.apache.org/dev/openpgp.html#generate-key

   Adding Keys

   # checkout the apache mxnet repo
   svn co https://dist.apache.org/repos/dist/dev/incubator/mxnet apache-mxnet
   cd apache-mxnet
   # update the KEYS file ...
   # commit the update
   svn commit -m “update keys file for xxx ” --username your_username --password your_passwd

Step 1.4. Cut the Release Branch

1. The release candidate should contain all planned features, bug fixes, and code changes above. The release candidate commit should have passed the merge build, pip builds, nightly tests. Docs should also be manually built locally & checked for correctness. TODO: how to retrieve the commit hash.
2. Manual Docs Build - 
   
   1. The build_all_versions.sh must also be updated with the correct tag
   2. This script must be built locally to test docs (confirmprocedure with Santhosh, Yao) and automate after 0.12.0.

3. Checkout the commit into a new branch "v#.#.#" and push it (It might be a good idea to do this in advance and freeze the branch)

Step 1.5. Tag release candidate (To be done by a committer)

1. Go to the GitHub repo’s “releases” tab
2. Click “Draft a new release”

1. 1. • Provide the release tag in the form of “1.0.0.rc0” where 0 means it’s the first release candidate
      • Select the commit by clicking Target: branch > Recent commits > $commit_hash 
      • Copy and paste NEWS.md change into the description box from here
      • Select “This is a pre-release"

Step 1.6. This step has not been done in the past 

Tag all the dependent submodules for every MXNet release. If a code-change (e.g. bug-fix) is required to a dependent sub-module then we take a branch from the tag and apply the code-change only to the branch for the sub-module so that the change is minimal. This should allow the MXNet release process to have better convergence towards a stable release.

Step 1.7. Create artifacts for the release and push to the dist folder

a) The src tar - apache-mxnet-src-#.#.#.rc0-incubating.tar.gx:

• • • Clone the Repo and checkout the release branch 
    • remove R-package until the licensing issue is resolved
    • Remove all the .git files
    • Remove all other files of the form .* (eg .travis, .DS_Store etc)
    • on MacOS use gnu-tar
    • Try to untar it in a different type of machine and try a classic build with `make`. Follow build instructions in the "Build from Source" section http://mxnet.incubator.apache.org/get_started/install.html

git clone git@github.com:apache/incubator-mxnet.git --recursive apache-mxnet-src-0.12.0.rc0-incubating
git checkout v0.12.0
git submodule update --init --recursive
git checkout 0.12.0.rc0
rm -rf R-package/*
rm -rf R-package
rm -rf .DS_Store
rm -rf .git*
brew install gnu-tar 
gtar -czvf apache-mxnet-src-0.11.0.rc3-incubating.tar.gz apache-mxnet-src-0.12.0.rc0-incubating

b) apache-mxnet-src-#.#.#.rc0-incubating.tar.gz.asc: 

details here: http://www.apache.org/dev/release-signing.html#openpgp-ascii-detach-sig

c) Create MD5 checksum : apache-mxnet-src-#.#.#.rc0-incubating.tar.gz.md5

d) Create SHA checksum: apache-mxnet-src-#.#.#.rc0-incubating.tar.gz.sha512

gpg --armor --output apache-mxnet-src-0.11.0-incubating.tar.gz.asc --detach-sig apache-mxnet-src-0.11.0-incubating.tar.gz

md5 apache-mxnet-src-0.11.0-incubating.tar.gz > apache-mxnet-src-0.11.0-incubating.tar.gz.md5
shasum -a 512 apache-mxnet-src-0.11.0-incubating.tar.gz > apache-mxnet-src-0.11.0-incubating.tar.gz.sha512

e) Create a folder for this RC in the dist folder: 0.12.0-incubating.RC0 folder 

# Checkout the Apache directory in Apache distribution SVN "dev" repo
$ svn co https://dist.apache.org/repos/dist/dev/incubator/mxnet
# select p
# Make directory for this RC in the above directory
$ cd mxnet
$ mkdir #.#.#.rc0
# Move artifacts into this folder
$ cp ../apache-mxnet-src-#.#.#.rc0-incubating.tar.gz* #.#.#.rc0
$ svn add #.#.#.rc0
$ svn commit -m "Add mxnet-#.#.#.rc0" --username "lxn2"

Step 1.8. Validate release package (Committer or Contributer)

As per the Apache documentation, verify that the release candidate artifacts satisfy the following:

• • PGP signatures and SHA256/MD5 checksum verification - 

svn co https://dist.apache.org/repos/dist/dev/incubator/mxnet && cd mxnet/#.#.#.rc0
brew install gpg coreutils
gpg --import ../KEYS

gpg --verify ./apache-mxnet-src-0.11.0.rc3-incubating.tar.gz.asc
gsha512sum --check  ./apache-mxnet-src-0.11.0.rc1-incubating.tar.gz.sha512
gmd5sum --check ./apache-mxnet-src-0.11.0.rc3-incubating.tar.gz.md5

• • Test that a build is successful - spinning up a deep learning Ubuntu AMI will give you an environment with all dependencies to build. A `make -j $(nproc) USE_OPENCV=1 USE_BLAS=openblas USE_CUDA=1 USE_CUDA_PATH=/usr/local/cuda USE_CUDNN=1` should do.
  • DISCLAIMER is correct, filenames include “incubating”
  • LICENSE and NOTICE files are correct and dependency licenses are acceptable

1. 1. 1. LICENSE and NOTICE files at the root of the artifact directory must only reflect the contents of the artifact in which they are contained.
      2. See:

• • • • LICENSE file requirements
      • LICENSE requirements for distribution artifacts with multiple licenses
      • NOTICE file requirements (Check Copyright year) - see also https://www.apache.org/legal/src-headers.html
      • Apache Legal
      • Acceptable and Unacceptable Dependency Licenses
  • All source files have license headers where appropriate, RAT checks pass - TODO - add instructions - see https://creadur.apache.org/rat/
  • The provenance of all source files is clear (ASF or software grants)

2. Running the voting process for a release:

Step 2.1. Vote on dev@ 

The full voting process is two phases: 3 days on dev@mxnet.apache.org, 3 days on http://general@incubator.apache.org.

For the dev@ vote, there must be at least 3 +1 votes and more +1 votes than -1 votes. Once that quorum has been reached, the vote then moves onto the general@ vote, where anyone can contribute a vote, but only MXNet PMC votes are binding. To pass, there must be 3 +1 PMC votes and more +1 votes than -1 votes. Send out a notice to vote.

To: dev@mxnet.apache.org

Subject: [VOTE] Release MXNet version 0.11.0.RC#

This is the vote to release Apache MXNet (incubating) version 0.11.0. Voting will start now and close $utc_now+72.

Link to release notes: <Link>

Link to release candidate 0.11.0.rc0: <Link>

Link to pip build: <Link>

Please remember to TEST first before voting accordingly:

+1 = approve

+0 = no opinion

-1 = disapprove (provide reason)

Step 2.2. Send out the Vote Results on dev@

To: dev@mxnet.apache.org

Subject: [RESULTS] [VOTE] Release MXNet version 0.11.0.RC#

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.

Step2.3. Triage issues and revote if necessary 

Should any vote fail to reach quorum or release manager determines that another RC needs to go out, the release manager should triage the issues, create GitHub issues, and move to fix the issues. Once fixed, make changes to NEWS & README.md in case it specifically lists the old RC# number. Start the process for another release candidate. In the new voting email, detail what has changed since the last release candidate. Repeat until the vote passes.

To: dev@mxnet.apache.org

Subject: [CANCELLED] [VOTE] Release MXNet version 0.11.0.RC#

    We are CANCELLING this vote because...

    We will address this issue and send out RC#+1 for another vote.

Step 2.4. Start a vote on general@

This is a call for a releasing Apache MXNet #.#.#-incubating, release
candidate #.

Apache S2Graph community has voted and approved the release.

Vote thread:
https://lists.apache.org/#######

Result thread:
https://lists.apache.org/#########

The source tarball, including signatures, digests, etc. can be found at:
https://dist.apache.org/repos/dist/dev/incubator/mxnet/########

The tag to be voted upon is v0.2.0-incubating-rc3:
<link>

The release hash is #########:
<link>

Release artifacts are signed with the following key:
<link>

KEYS file available:
<link>

For information about the contents of this release, see:
<link to release notes>

The vote will be open for 72 hours.

[ ] +1 Release this package as 0.1.0
[ ] +0 no opinion
[ ] -1 Do not release this package because...

3. Finalizing and posting a release:

3.1. Marking & Publishing the Official release

Once the release candidate passes the vote, we draft the official release on GitHub and rename the release candidate as the official release.

Step 3.1.1: Draft official release on GitHub:

• • Go to the GitHub repo’s “releases” tab
  • Click “Draft a new release”
  • Provide the release tag in the form of “0.12.0”
  • Select the commit by clicking Target: master > the passing release candidate tag
  • Copy and paste NEWS change into the description box

Step 3.1.2: Rename and publish the source package:

First upload to dev and then move to releases as follows 

#create a directory under releases -  https://httpd.apache.org/dev/release.html

This process needs to change -> http://www.apache.org/dev/release-download-pages.html

# Step 1: Download and Untar
tar -zxvf apache-mxnet-src-0.11.0.rc3-incubating.tar.gz

# Step 2: rename (remove the rc) and tar again
mv apache-mxnet-src-0.11.0.rc3-incubating apache-mxnet-src-0.11.0-incubating
gtar -czvf apache-mxnet-src-0.11.0-incubating.tar.gz apache-mxnet-src-0.11.0-incubating

# Step 3: Resign now
 
# Step 4: First upload here - svn mv https://dist.apache.org/repos/dist/dev/incubator/mxnet/0.11.0/
 
# Step 5: Move from dev to release
svn mv https://dist.apache.org/repos/dist/dev/incubator/mxnet/0.11.0/ https://dist.apache.org/repos/dist/release/incubator/mxnet/ --message "0.11.0 release moving from dev to release repo"

 
# Wait 24hours for the src mirroring. The final download page for the announce email is somewhere here (example 0.11.0) - https://www.apache.org/dyn/closer.cgi/incubator/mxnet/0.11.0-incubating/

Step 3.1.3: Download the nightly pip build, rename, and publish:(by Sheng)

Step 3.1.4: Build, test, and publish the Docker images: (by Meghna)

This was done as follows in 0.11.0. In the future use the automated pipeline - 

• • • • Update the tag in the tool.sh file or select the correct tag in the Jenkins Job
      • Select the correct Repo name  = mxnet
      • Trigger the Job with IS_PUBLISH=false
      • Login to the slave and test each image for correct version by checking logs and/or Readme. 
      • Manually upload the 20 images that are built. 

Step 3.1.5: Verify the resources are uploaded

• • Check that the resources are present in http://www.apache.org/dist/incubator/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.  

Step 3.1.6: Test

Test multinode and multi gpu (kvstore=1)

3.2. Update the MXNet website

Now that a new version has been drafted on GitHub with source and pip packages published, we need to update the MXNet website. Go to builds.apache.org and find job “incubator-mxnet-build-site”. Click “Build with Parameters”, select the release tag, and build. The docs will be published to incubator.mxnet.apache.org.

Manually update the website’s download links:

• • TODO: link to Apache mirror source, pgp, sha, md5

3.3. Review the announcement email content on private@mxnet.incubator.apache.org before sending the announcement.

3.4. Check if this release has to go out on a blog on blogs.apache.org 

3.5. Announce the release

Once everything is working (website docs, website changes, 24 hours after upload) create an announcement on the website and then send an e-mail to the mailing list. http://www.apache.org/legal/release-policy.html#release-announcements

Send an email to announce@apache.org, general@incubator.apache.org, and dev@mxnet.incubator.apache.org with the subject: [ANNOUNCE] Apache MXNet <release number> Release and a body along the lines of:

3.6. Bump up the versions on the master  

1. Merge the PR you created for the release branch into the master
2. Add a new PR to update the version to one up/or next release for pip-releases

Enjoy an adult beverage (or bubble tea) of your choice, and congratulations on making a MXNet release.

Notes for reference

*NOTES FROM DOCS FOR REFERENCE:*
http://incubator.apache.org/guides/releasemanagement.html

   - 3 +1 votes from IPMC members (these are the votes that count but we
   should open up to the whole podling community)
   - For podlings, 2 additional constraints:
   - Release artifacts must include “incubating” in final file name (ex:
      apache-mxnet-src-0.10.1-incubating.tar.gz)
   - Release artifacts must include disclaimer in the release artifacts


   - The Incubator PMC expects the source releases to be staged on
   https://dist.apache.org/repos/dist/dev/incubator/podlingName so that
   they can easily be moved to the release location via svn mv   (
   http://www.apache.org/dist/incubator/)
   - After graduating, RC’s go into https://dist.apache.org/repos/dist/dev/
   and official releases go into https://dist.apache.org/repos/dist/release/


http://incubator.apache.org/guides/branding.html#disclaimers

   - Apache Press Team [http://www.apache.org/press/index.html#whoweare]
   must review and coordinate releases for branding
   - On website and in release DISCLAIMER file:
   - Apache Podling-Name is an effort undergoing incubation at The Apache
      Software Foundation (ASF), sponsored by the name of Apache TLP sponsor.
      Incubation is required of all newly accepted projects until a further
      review indicates that the infrastructure, communications, and decision
      making process have stabilized in a manner consistent with other
successful
      ASF projects. While incubation status is not necessarily a reflection of
      the completeness or stability of the code, it does indicate that the
      project has yet to be fully endorsed by the ASF.
      - Website should include Apache Incubator logo:
      http://incubator.apache.org/guides/press-kit.html


   - Release should include:
      - DISCLAIMER
      - LICENSE
      - NOTICE - attribution notices


http://www.apache.org/legal/release-policy.html

   - A release must contain source package which is cryptographically
   signed by Release Manager with detached signature. It must be tested prior
   to voting for release.
   - Release must only contain appropriately licensed code
   - Please ensure you wait >=24 hours after uploading a release before
   making announcements so mirrors catch up
   - Releases of more than 1GB of artifacts require a heads-up to
   Infrastructure in advance.
   - Which directory for what build?
   http://www.apache.org/legal/release-policy.html#build-directories


http://www.apache.org/dev/release-distribution.html

   - Artifacts MUST be accompanied by:
      - apache-mxnet-src-0.10.1-incubating.asc - contains OpenPGP
      compatible ASCII armored detached signature
      - apache-mxnet-src-0.10.1-incubating.md5 - MD5 checksum
      - apache-mxnet-src-0.10.1-incubating.sha - SHA checksum (SHOULD)
   - Publish KEYS file in distribution directory root
      - Signing keys MUST be published in KEYS file, SHOULD be available in
      global public keyserver
      http://www.apache.org/dev/release-signing#keyserver, SHOULD be linked
      into web of trust
      - Keys MUST be RSA & 4096 bits


http://www.apache.org/dev/release-publishing.html

   - Apache RAT can assist in checking license compliance
   http://creadur.apache.org/rat/
   - Eventually we should set up a build system to sign our releases with
   cryptographic signatures. For now we’ll do it manually.


http://www.apache.org/dev/release-signing.html

   - Create a signature and sign releases as mentioned above