Hello all,
As you may have noticed, we have successfully navigated the ASF release
process for for our first release: Apache Mynewt 0.8.0-b1-incubating. I
thought it would be a good idea to compile a list of issues and lessons
learned as they relate to our first release through the ASF. There is a
lot of development work planned for future releases, and I think we
should do what we can to ensure a smooth release process in the future.
First, here are some issues that were identified during the first
release. We need to fix these before our next release.
(1) Apache-licensed newt binaries
We weren't able to release convenience binaries of the newt tool because
of an LGPL-licensed dependency. The particular dependency that caused
this issue (yaml.v2) has since been removed from newt, so this won't
pose a problem in the next release. However, I believe the takeaway
message here is that we need to treat all dependencies as though there
were part of the source package. This goes for all tools in any of our
repositories, e.g., newtmgr. See the end of this email for notes on
managing licenses.
(2) Improve the top-level README.md files.
I think we all agree that the readme files in the first release are
lacking. The readme files should provide:
* A general overview of what the product does.
* Simple directions for building the product.
* Additional usage information (we will probably want to include a
pointer to the online Mynewt documentation here).
It is OK if the readme files duplicate some text from the online
documentation. What is important is that they function as a quick
standalone introduction.
(3) Release notes
0.8.0-b1 is exceptional in that it is our first release. In subsequent
releases we will want to specify what has been added or fixed since the
last release, as well as highlight known issues.
(4) Fix our release naming procedure.
For a beta release whose name includes a "-b<#>" element, this element
should be the last thing in the name. To demonstrate, here is a
comparison of the (bad) b1 name and the (good) b2 name that we will use:
* (bad): Apache Mynewt 0.8.0-b1-incubating
* (good): Apache Mynewt 0.8.0-incubating-b2
----
Finally, I wanted to add a note on licensing issues. The biggest
roadblock in the release process involved making sure that all
non-Apache-licensed dependencies were properly called out in our
documentation. Larva, in particular, is shipped with a lot of
third-party code, and staying on top of the licensing implications will
be challenging. Apache Rat (Release Audit Tool) is quite helpful in
making sure all the non-apache dependies are accounted for. Apache Rat
is available here: http://creadur.apache.org/rat/
For subsequent releases, I recommend the following procedure for
auditing third-party dependencies:
1. Run the Rat tool from the base directory of the repository being
audited.
2. Look at the source files flagged by Rat.
A. If any files use licenses that are not Apache-compatible
(http://www.apache.org/legal/resolved.html#category-x), then the
files must be removed from the release.
B. For files that use Apache-compatible licenses:
a. 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.
b. Add the filenames 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 licenses. This change
prevents Rat from flagging the same files during subsequent
executions.
Unfortunately, Rat does not appear to support more than one directory in
filename paths in its exclude files. I.e., the following entries are
OK:
crc16.*
system_nrf52.h
libs/baselibc
But these arent:
fs/nffs/src/crc16.c
hw/mcu/nordic/nrf52xxx/include/mcu/system_nrf52.h
This could become problematic if a repository contains two files with
the same name.
All questions, suggestions, and other comments are welcome.
Thanks,
Chris
