Analysis of our first release process

[Christopher Collins <ch...@runtime.io>]

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

Re: Analysis of our first release process

[Justin Mclean <ju...@classsoftware.com>]

Hi,

> What type of warnings do we want to provide in the Newt tool for non-ASF compatible licenses.
> 
> - Do we want to have a list of these 3rd party package repositories in the official ASF documentation?

General practice is to prompt the user when installing something that is not Category A.

> - How do we provide binary and source distributions of the Newt tool.

For the next vote vote on both a source and convenience binary release at the same time - now the GPL dependancy is gone.

Thanks,
Justin

Re: Analysis of our first release process

[Sterling Hughes <st...@apache.org>]

On 3/1/16 4:02 PM, Justin Mclean wrote:
> Hi,
>
> Great summary!
>
>> 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.
>
> JFYI this is usually done in a separate file call RELEASE_NOTES or similar. For example see [1] but there no prescribed way of doing this it’s up.
>

yes.  I think next release has to spend quite a bit of time on this 
file, given the early state of OS releases, we need to be super clear 
with people about where we are.

>> (4) Fix our release naming procedure.
>
> Again up to the PMC how they name releases, other than having the project name, ‘incubating’ and (optionally) apache. “rc" (for release candidate) is usually used rather than "b” tends to be typical but again totally up to the PMC. That those names seem fine to me.
>
> Having the release process documented would be a good idea so that other committers can make a release if they want.
>

+1.  I think we'll need to document two things on the Mynewt wiki, 
branching strategy and release process.

1- We should document the current release process that we used, along 
with thoughts on the improvements

2- I'll work on documenting our branching strategy.

I think there are a number of things we'll want to discuss re [1], 
including:

- How do we manage non-ASF compatible packages.  Do they get distributed 
on Github, and does the ASF repository point to these external packages.

What type of warnings do we want to provide in the Newt tool for non-ASF 
compatible licenses.

- Do we want to have a list of these 3rd party package repositories in 
the official ASF documentation?

- How do we provide binary and source distributions of the Newt tool. 
My instinct is that close to 99% of our users will take the newt binary 
as opposed to source, so we need to make this easy, while still 
following the ASF philosphy of source first releases.

- How do we want to allow people to access the ASF package repository 
with releases of newt.  For example, by default should a newt release 
point to a specific tag on the incubator-mynewt-larva package 
repository?  Should we allow people to chose different versions based on 
a tag / branch strategy here?

- How do we facilitate upgrade of packages when migrating to a new release.

Chris, if you take a first pass at this with what we've done for this 
release, I can take a second pass, and then let's send around to the 
list for discussion?

Cheers,
Sterling

Re: Analysis of our first release process

[Justin Mclean <ju...@me.com>]

Hi,

Great summary!

> 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.

JFYI this is usually done in a separate file call RELEASE_NOTES or similar. For example see [1] but there no prescribed way of doing this it’s up.

> (4) Fix our release naming procedure.

Again up to the PMC how they name releases, other than having the project name, ‘incubating’ and (optionally) apache. “rc" (for release candidate) is usually used rather than "b” tends to be typical but again totally up to the PMC. That those names seem fine to me.

Having the release process documented would be a good idea so that other committers can make a release if they want.

Thanks,
Justin

1. https://github.com/apache/flex-sdk/blob/develop/RELEASE_NOTES