Release Process

This page describes the process of releasing a new version of Mynewt through the ASF.

Overview

A Mynewt release consists of three pieces:

1. Larva
2. Newt, Newtmgr, and Newtvm
3. Tadpole

Each of these pieces has its own git repository:

When you are ready to release a new version of Mynewt, use the below steps to guide you through the process.

Step 1: Ensure all Tests Pass

TBD.

Step 2: Audit licenses of third-party code

Every third-party library included in a release that is not Apache-licensed has to be accounted for.  For information about what licenses are Apache-compatible, see the following pages:

• Allowed: http://www.apache.org/legal/resolved.html#category-a
• Not allowed: http://www.apache.org/legal/resolved.html#category-x

Download Rat

To perform a license audit, you will need to use a tool called Apache Rat.  Download Rat here: http://creadur.apache.org/rat/download_rat.cgi

Rat Usage

Rat checks all the files in the specified path for something resembling an Apache license.  Files that do not contain an Apache licensed get flagged.  A .rat-excludes file is used to indicate which files should be ignored by Rat.  Once a non-Apache file has been accounted for, its name can be added to the excludes file.

To execute the Rat tool from the command-line:

1. Change to the base directory of the repository you wish to audit (e.g., ~/dev/larva).
2. Run the following command:

      java -jar <rat-directory>/apache-rat-0.11.jar -E .rat-excludes -d .

Where <rat-directory> is the location where you unpacked the rat tool.

Example:

[ccollins@ccollins-mac:~/repos/larva]$ java -jar ~/Downloads/apache-rat-0.11/apache-rat-0.11.jar -E .rat-excludes -d .
*****************************************************
Summary
-------
Generated at: 2016-03-03T19:28:50-08:00
Notes: 4
Binaries: 2268
Archives: 0
Standards: 3926
[...lots of output snipped...]

Audit Procedure

1. Run the Rat tool from the base directory of the repository being audited.
2. Look at the source files flagged by Rat.  For each file:
   1. If the file was created for Mynewt (i.e., not third-party), then it is missing the Apache license text.  Copy the text from another Mynewt source file and paste it at the top of the problematic file.  You can verify that the license text is correct by comparing it to the text at the bottom of this page: http://www.apache.org/licenses/LICENSE-2.0
   2. If the file is third-party and it uses a license that is not Apache-compatible (http://www.apache.org/legal/resolved.html#category-x), then the files must be removed from the release.
   3. If the file is third-party and it uses a license that is Apache-compatible:
      1. Add a pointer at the end of the repository's LICENSE file indicating that the library is included in the product and that it is licensed in an Apache-compatible way.  The LICENSE file should be located in the root of the repository.  A single pointer can account for an entire library if the library is isolated in the directory tree.  If Mynewt sources files are intermixed with third-party files, each third-party file must be specified in the LICENSE file.
      2. Add the filename to the repository's .rat-excludes file. This file should be in the repository's base directory. Preface the addition with a comment explaining which library the files are from and how they are licensed.  This change prevents Rat from flagging the same files during subsequent executions.

Step 3: Tag the Repositories

Each git repository must be tagged with the name of the release.  Tagging the repositories makes it easy to determine exactly what when into the release.  The tag should be named as follows:

• mynewt_<version-number>_tag

Replace periods in the version number with underscores.  If this is a beta release, append b<number> to the version-number.  For example, 0.8.0 beta 2 should have the following tag:

• mynewt_0_8_0_b2_tag

Tag the repository with the following git commands:

    git tag -a <tag-name> -m <commit-message>
    git push origin <tag-name>

The first command creates a tag in your local repository.  The second pushes the tag to the remote server.

Example:

[ccollins@ccollins-mac:~/repos/larva]$ git tag -a mynewt_0_8_0_b1_tag -m 'Mynewt 0.8.0 B1'
[ccollins@ccollins-mac:~/repos/larva]$ git push origin mynewt_0_8_0_b1_tag

Repeat this procedure for each of the repositories.  Use the same tag name for each repository.

Step 4: Create the source release artifacts

Note: To complete this step you will need to publish a GPG code signing key.  This something you only have to do once.  If you have not done this, see: TBD.

Each source release consists of three artifacts:

1. Gzipped tarball.
2. A SHA512 hash of the gzipped tarball.
3. A detached signature generated by signing the gzipped tarball with your code signing key.

Source release artifacts must be named as follows (file extension excluded):

• apache-<product>-<version>-incubating[-b#]

The trailing -b# is only included if this is a beta release.

For example, for 0.8.0 beta 2, the three source artifacts would have the following names:

• apache-larva-0.8.0-incubating-b2
• apache-newt-0.8.0-incubating-b2
• apache-tadpole-0.8.0-incubating-b2

The following procedure can be used to produce the source artifacts:

1. Grab the mynewt-archive.sh script (https://github.com/runtimeinc/mynewt_tools/raw/master/mynewt-archive.sh) if you don't already have it.  Put it somewhere in your PATH, or adjust the following steps as needed.
2. Change to the base directory of the git clone.
3. mynewt-archive.sh <tag-name> <destination-dir/artifact-name> (note: you will be prompted for your key password)

The <tag-name> is the name of the tag you created in step 3.  The <destination-dir/artifact-name> field is best illustrated with an example:

[ccollins@ccollins-mac:~/repos/larva]$ mynewt-archive.sh mynewt_0_8_0_b2_tag ~/tmp/rel/bin/apache-larva-0.8.0-incubating-b2

The above invocation will create the following three files:

    # Source tarball.
    ~/tmp/rel/bin/apache-larva-0.8.0-incubating-b2.tgz

    # Detached signature.
    ~/tmp/rel/bin/apache-larva-0.8.0-incubating-b2.tgz.asc

    # SHA512.
    ~/tmp/rel/bin/apache-larva-0.8.0-incubating-b2.tgz.sha

Apply this process to each repository (larva, newt, and tadpole).

Note: You do not need to make a fresh git clone for the above procedure.  The mynewt-archive.sh script uses the git archive command, which packages the source files exactly as they were tagged in git.

Step 5: Verify the signatures

The mynewt-archive.sh script verifies the signatures after they are created, but you might want to double-check that everything is good.  Run the following command for each detached signature (.asc) file:

    gpg2 --verify "<tgz-file>" "<asc-file>"

The output will indicate that the signature matches the tarball (or not!).

If all your artifacts are in the same directory, you can simplify the process with a script, e.g.,

    for i in *.asc ; do echo ">>> $i <<<" && gpg2 --verify "$i" "${i%.asc}" ; done

Step 6: Upload the artifacts to the release candidate svn server

1. Check out the mynewt directory from the svn server:

    svn co https://dist.apache.org/repos/dist/dev/incubator/mynewt

2. Make sure the KEYS file is up to date

If you used a new key to sign the release, you need to append the text representation of your key to the KEYS file.  The KEYS file is located in the base mynewt path of the svn server.

    cat <your-key-file> >> KEYS

3. Create a new subdirectory for the release in the mynewt directory

The directory should be named as follows:

• apache-mynewt-<version>-incubating[-b#]

E.g.,

[ccollins@ccollins-mac:~/repos/incubator/mynewt]$ mkdir apache-mynewt-0.8.0-incubating-b2
[ccollins@ccollins-mac:~/repos/incubator/mynewt]$ svn add apache-mynewt-0.8.0-incubating-b2

4. Add the build artifacts to the new subdirectory

[ccollins@ccollins-mac:~/repos/incubator/mynewt]$ mv ~/tmp/release/apache-mynewt-0.8.0-incubating-b2/* apache-mynewt-0.8.0-incubating-b2/
[ccollins@ccollins-mac:~/repos/incubator/mynewt]$ svn add apache-mynewt-0.8.0-incubating-b2/*

5. Commit

[ccollins@ccollins-mac:~/repos/incubator/mynewt]$ svn ci

Step 7: Send a vote email to the dev list

Call for a vote for the new release by sending an email to dev@mynewt.incubator.apache.org.  You can use the following template: TBD.

The vote must remain open for at least 72 hours.  You can keep the vote open longer if you wish (e.g., if the necessary number of +1 votes have not been accumulated yet).

Step 8: Send a vote-result email to the dev list

You can use the following template: TBD.  The vote passes if the following two criteria are met:

• At least three binding +1 votes.
• The total vote tally is >= half the number of binding votes (i.e., majority consensus).

If the vote doesn't pass, the process ends here.  You will need to restart the process after the problems are fixed.  If the vote does pass, proceed to step 9.

Step 9: Send a vote email to the gen list

This is similar to the dev vote email.  The differences are:

• Email recipient is: general@incubator.apache.org
• A different set of people have binding votes.

You can use the template here: TBD.

Step 10: Send a vote-result email to the gen list

You can use the following template: TBD.  The vote pass criteria are the same as those of the dev vote:

• At least three binding +1 votes.
• The total vote tally is >= half the number of binding votes (i.e., majority consensus).

If the vote doesn't pass, the process ends here.  You will need to restart the process after the problems are fixed.  If the vote does pass, proceed to step 11.

Step 11: Move the release artifacts to the release directory on the svn server

The release directory is: https://dist.apache.org/repos/dist/release/incubator/mynewt

The release subdirectory (and the KEYS file, if you changed it) should be committed to the above directory.

Step 12: Announce the release on the dev list

TBD!