Oslo/ReleaseProcess

= Oslo Library Release Process =

Version Numbers
See Oslo/VersioningPolicy for guidelines for choosing version numbers.

Post-Release Tracking
Because Oslo libraries tend to generate releases far more often than the integrated projects, we use "post-release" tracking rather than major milestone predictive tracking. Release series are named after the current development cycle code name, using all lower case letters. Each library should also have a single open "next-$series" milestone within the series. Active work is placed in the milestone, and the milestone is renamed as part of the release process to indicate that the completed work was done in the given release.

For example, oslo.log has a "kilo" series and a "next-kilo" milestone. Blueprints and bugs are added to "next-kilo" as work begins. When release 0.1.0 of oslo.log is tagged, the "next-kilo" milestone is renamed to "0.1.0" and a new "next-kilo" milestone is created. Any blueprints or bugs *not* completed as part of the 0.1.0 release is moved to the new milestone and work continues.

The oslo-incubator uses major milestone tracking ("kilo-1", "kilo-2", etc.) because it is not technically released and because we use the oslo-incubator project for blueprints and specs that are not related to a single library.

Installing Release Tools
The release management team has created some tools to help manage our releases. To install the tools, check out a copy of the openstack-infra/release-tools git repository, create a virtualenv, and install the dependencies:

$ git clone git://git.openstack.org/openstack-infra/release-tools $ cd release-tools $ virtualenv .venv $ source .venv/bin/activate $ pip install -r requirements.txt --allow-external lazr.authentication --allow-unverified lazr.authentication

Setting Up GPG
OpenStack releases rely on GPG-signed tags in the git repository. You will need a GPG key configured on the system where you are going to tag releases. It is good to have your key signed by other members of the community to establish a web-of-trust. There are usually in-person meetings at the summits and mid-cycle meetups to take care of key signings.

If your default Git commit email address is not included in your gpg key, you will need to add it in order to continue (or change your default git commit address). This can be done using the following steps, based on the instructions in this blog post, and will not invalidate your key:
 * 1) $ gpg --edit-key your.email@your-domain.com
 * 2) At the gpg command line, type "adduid"
 * 3) When prompted, enter your real name and address.  These must match your git commit settings.
 * 4) Leave the comment field blank (this is a change from the blog post instructions).
 * 5) If everything looks correct, hit 'o'
 * 6) Back at the gpg command line, press the number associated with your newly added uid.
 * 7) Enter 'trust'
 * 8) Press 5 to trust yourself ultimately
 * 9) Type 'quit' at the gpg prompt and answer 'y' when it asks you to save your changes.

Setting up Launchpad
The release tool connects to launchpad, which requires oauth authorization. Setting this up usually requires a web browser, and some users have experience trouble with console browsers such as lynx. You may, therefore, want to run the release scripts on your local system where a regular GUI browser is available, instead of on a remote server where only the terminal is available to you.

You need to be a member of the oslo-drivers team to have permission to create and edit milestones. If you are not on the member list for https://launchpad.net/~oslo-drivers ask one of the other members to add you.

Setting up Gerrit Permissions
After the release tool checks out the code repository specified and creates the signed tag, it pushes the tag up to gerrit. You need special permissions to push tags to gerrit, so make sure you are in the release team for the project you are trying to release. Another member of the same gerrit release team, or the infra team, can help you set this up.

Releasing a Library
Use the release_library.sh script to tag a release and update launchpad.

$ ./release_library.sh Usage: ./release_library.sh series version SHA project Example: ./release_library.sh juno 1.0.0 HEAD oslo.rootwrap

The first time you run this, it will open a browser window where Launchpad will ask you what permissions to grant the application. The easiest option is just to allow all.

After the repository is tagged, the release tool updates all of the closed bugs for the project, ensuring they are in the next-$series milestone. It then renames that milestone to the version number you have specified, making release notes and tracking easier.

At that point the script prints a message like "Fix any leftover bugs manually and press key to continue...". STOP HERE AND GO LOOK AT LAUNCHPAD.

This is your opportunity to fix any bugs that need to be marked as "Fix Released" but for which the API timed out (this happens frequently when too many projects are associated with the same bug). It is also your opportunity to move any bugs that aren't closed to a different milestone, before the current milestone is closed.

First, create a new next-$series milestone by clicking the "Create milestone" link on the series page.

Next, if there are any blueprints or bugs in the version milestone that are *not* completed, move them to next-$series.

Finally, if there are any bugs in the version milestone that are completed but not marked as "Fix Released", update their state. You may have to try several times if there are timeout errors.

Only when this is done, go back to the terminal and press return to continue the process. At this point, the script closes the old milestone so no new items can be added to it.

Send Release Notes
We generate release notes for library releases directly from the git logs, so refresh your local sandbox:

$ git pull

The release notes script is in oslo-incubator/tools:

$ ./tools/release_notes.py ../$libdir $prevrel $relnum

Email the output to the openstack-dev mailing list.