This page describes the process of releasing a new version of Mynewt through the ASF.
A Mynewt release consists of three pieces:
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.
There may be some changes intended for the release that never made it in. Review the outstanding pull requests in the three github mirrors and make sure none of them need to make it into the release. If any of them should be in the release, they need to be merged before you can proceed with the release process.
Piece | URL |
---|---|
Blinky | https://github.com/apache/incubator-mynewt-blinky/pulls |
Core | https://github.com/apache/incubator-mynewt-core/pulls |
Newt, etc. | https://github.com/apache/incubator-mynewt-newt/pulls |
The Mynewt testing procedure is underdeveloped. Testing consists of two steps:
$ newt test all ...lots of compiling and testing... ...about 2 minutes later ... Archiving bootutil.a Linking test_bootutil Executing test: /Users/ccollins/tmp/myproj/bin/unittest/libs/bootutil/test_bootutil Passed tests: [net/nimble/host fs/nffs libs/os hw/hal libs/mbedtls libs/util sys/config libs/bootutil] All tests passed |
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:
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 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:
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/core]$ 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...] |
Unfortunately, Rat does not appear to support more than one directory in filename paths in the exclude file. I.e., the following entries are OK:
|
Each git repository must be tagged with the name of the release. Tagging the repositories makes it easy to determine exactly what went into the release. The tag should be named as follows:
The rc<#> is the release candidate number. Start with an rc of 1; increment this number each time you have to cancel and restart the release process. 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 rc3 should have the following tag:
Tag the repository with the following git commands:
git tag -a <tag-name> -m <commit-message>
git push origin --tags
The first command creates a tag in your local repository. The second pushes the tag to the remote server.
You will also want to create a second tag that doesn't specify an rc number. This tag is necessary so that the release can be properly tested. For example, the core repository contains a repository.yml file mapping version numbers to tag names. This file has to be accurate both during and after the release process, so it needs to specify the final tag name from the start.
Example:
[ccollins@ccollins-mac:~/repos/core]$ git tag -a mynewt_0_8_0_b2_rc3_tag -m 'Mynewt 0.8.0 B2, rc3' [ccollins@ccollins-mac:~/repos/core]$ git tag -a mynewt_0_8_0_b2_tag -m 'Mynewt 0.8.0 B2' [ccollins@ccollins-mac:~/repos/core]$ git push origin --tags |
Repeat this procedure for each of the repositories. Use the same tag names for each repository.
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: Code Signing Keys.
Each source release consists of three artifacts:
Source release artifacts must be named as follows (file extension excluded):
The intermediate -b# is only included if this is a beta release.
For example, for 0.8.0 beta 2 rc3, the three source artifacts would have the following names:
The following procedure can be used to produce the source artifacts:
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/core]$ mynewt-archive-src.sh ~/releases/0.8.0-b2/rc3/apache-core-0.8.0-b2-incubating mynewt_0_8_0_b2_rc3_tag |
The above invocation will create the following three files:
# Source tarball. ~/releases/0.8.0-b2/rc3/apache-core-0.8.0-b2-incubating.tgz # Detached signature. ~/releases/0.8.0-b2/rc3/apache-core-0.8.0-b2-incubating.tgz.asc # SHA512. ~/releases/0.8.0-b2/rc3/apache-core-0.8.0-b2-incubating.tgz.sha |
Apply this process to each repository (core, newt, and blinky). Do not include the rc-number in the artifact names.
Note: You do not need to make a fresh git clone for the above procedure. The mynewt-archive-src.sh script uses the git archive command, which packages the source files exactly as they were tagged in git.
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: Code Signing Keys.
Binary releases contain the same artifacts as source releases:
Binary release artifacts must be named as follows (file extension excluded):
The intermediate -b# is only included if this is a beta release.
For example, for 0.8.0 beta 2 rc3, the two binary artifacts would have the following names:
The following procedure can be used to produce the binary artifacts:
The file list should consist of the following:
The LICENSE, NOTICE, and DISCLAIMER fails should be exactly those from the corresponding source release.
Example:
[ccollins@ccollins-mac:~/repos/newt]$ mynewt-archive-bin.sh ~/releases/0.8.0-b2/rc3/apache-newt-bin-osx-0.8.0-b2-incubating newt LICENSE NOTICE DISCLAIMER |
The above invocation will create the following three files:
# Binary tarball. ~/releases/0.8.0-b2/rc3/apache-newt-bin-osx-0.8.0-b2-incubating.tgz # Detached signature. ~/releases/0.8.0-b2/rc3/apache-newt-bin-osx-0.8.0-b2-incubating.tgz.asc # SHA512. ~/releases/0.8.0-b2/rc3/apache-newt-bin-osx-0.8.0-b2-incubating.tgz.sha |
Apply this process for each platform (osx and linux). Do not include the rc-number in the artifact names.
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
svn co https://dist.apache.org/repos/dist/dev/incubator/mynewt
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
The directory should be named as follows:
[ccollins@ccollins-mac:~/repos/dist.apache.org/repos/dist/dev/incubator/mynewt]$ mkdir -p apache-mynewt-0.8.0-b2-incubating/rc3 |
[ccollins@ccollins-mac:~/repos/dist.apache.org/repos/dist/dev/incubator/mynewt]$ cp ~/releases/0.8.0-b2/rc3/* apache-mynewt-0.8.0-b2-incubating/rc3/ [ccollins@ccollins-mac:~/repos/dist.apache.org/repos/dist/dev/incubator/mynewt]$ svn add apache-mynewt-0.8.0-b2-incubating |
[ccollins@ccollins-mac:~/repos/dist.apache.org/repos/dist/dev/incubator/mynewt]$ svn ci |
Call for a vote for the new release by sending an email to dev@mynewt.incubator.apache.org. A separate "[DISCUSS]" thread should also be opened to allow for discussion of the pros and cons of the release. These threads are kept separate so that the vote thread is not polluted with discussion.
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). The vote passes if the following two criteria are met:
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.
This is similar to the dev vote email. The differences are:
Some resources for writing this email:
The pass criteria are the same as those of the dev vote:
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 13.
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. What you put in this directory should be identical to what got put into the dev directory earlier in the process.
Send a release announcement to the following two recipients using your apache.org address.
Some resources for writing this email:
Notes: