minor mods to the release instructions
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/48d06240 Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/48d06240 Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/48d06240 Branch: refs/heads/master Commit: 48d06240189db8ff13107c57e4a37ec935703b65 Parents: 23f7951 Author: Alex Heneveld <[email protected]> Authored: Tue Sep 1 20:24:25 2015 +0100 Committer: Alex Heneveld <[email protected]> Committed: Wed Sep 2 09:22:44 2015 +0100 ---------------------------------------------------------------------- .../release-process/environment-variables.md | 8 ++--- .../release-process/make-release-artifacts.md | 6 ++-- .../committers/release-process/prerequisites.md | 31 +++++++++++++------- .../release-process/release-version.md | 11 +++++++ 4 files changed, 40 insertions(+), 16 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/48d06240/docs/website/developers/committers/release-process/environment-variables.md ---------------------------------------------------------------------- diff --git a/docs/website/developers/committers/release-process/environment-variables.md b/docs/website/developers/committers/release-process/environment-variables.md index a82f631..886d3c7 100644 --- a/docs/website/developers/committers/release-process/environment-variables.md +++ b/docs/website/developers/committers/release-process/environment-variables.md @@ -8,13 +8,13 @@ Many example commands in this section using variable names as placeholders for i releases. To allow these example commands to run unmodified, set these environment variables appropriately. {% highlight bash %} -# The version currently set on the master branch -OLD_MASTER_VERSION=0.7.0-SNAPSHOT +# The version currently set on the master branch (BROOKLYN_VERSION_BELOW) +OLD_MASTER_VERSION=0.9.0-SNAPSHOT # The next version to be set on the master branch -NEW_MASTER_VERSION=0.8.0-SNAPSHOT +NEW_MASTER_VERSION=0.NNN+1.0-SNAPSHOT # The version we are releasing now. While Brooklyn is in the Apache Incubator, this must be suffixed `-incubating`. -VERSION_NAME=0.7.0-incubating +VERSION_NAME=0.NNN.0-incubating # The release candidate number we are making now. RC_NUMBER=1 http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/48d06240/docs/website/developers/committers/release-process/make-release-artifacts.md ---------------------------------------------------------------------- diff --git a/docs/website/developers/committers/release-process/make-release-artifacts.md b/docs/website/developers/committers/release-process/make-release-artifacts.md index 135610aea..886f688 100644 --- a/docs/website/developers/committers/release-process/make-release-artifacts.md +++ b/docs/website/developers/committers/release-process/make-release-artifacts.md @@ -5,11 +5,11 @@ navgroup: developers --- A release script is provided in `release/make-release-artifacts.sh`. This script will prepare all the release artifacts. -It is written to account for several Apache requirements, so you are advised to use it rather than "rolling your own". +It is written to account for several Apache requirements, so you are strongly advised to use it rather than "rolling your own". The release script will: -- **Create source code and binary distribution artifacts** and place them in a directory on your workstation. +- **Create source code and binary distribution artifacts** and place them in a temporary staging directory on your workstation, usually `releases/`. - **Create Maven artifacts and upload them to a staging repository** located on the Apache Nexus server. The script has a single required parameter `-r` which is given the release candidate number - so `-r1` will create @@ -24,6 +24,8 @@ To run the script: It will show you the release information it has deduced, and ask yes-or-no if it can proceed. Please note that the script will thoroughly clean the Git workspace of all uncommited and unadded files. +**You really probably want to run this against a secondary checkout.** It will wipe `.project` files and other IDE metadata, and bad things can happen if an IDE tries to write while the script is running. Also as it takes a long time, this means your workspace is not tied up. One quick and easy way to do this is to `git clone` the local directory of your primary checkout to a secondary location. + A few minutes into the script you will be prompted for the passphrase to your GnuPG private key. You should only be asked this question once; the GnuPG agent will cache the password for the remainder of the build. http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/48d06240/docs/website/developers/committers/release-process/prerequisites.md ---------------------------------------------------------------------- diff --git a/docs/website/developers/committers/release-process/prerequisites.md b/docs/website/developers/committers/release-process/prerequisites.md index 086df5a..7c6708a 100644 --- a/docs/website/developers/committers/release-process/prerequisites.md +++ b/docs/website/developers/committers/release-process/prerequisites.md @@ -32,16 +32,24 @@ pre-release software to the global release mirror network! GPG keys -------- -The release manager must have a GPG key to be used to sign the release. +The release manager must have a GPG key to be used to sign the release. See below to install `gpg2` +(with a `gpg` alias). The steps here also assume you have the following set +(not using `whoami` if that's not appropriate): + +{% highlight bash %} +GPG_KEY=`whoami`@apache.org +SVN_USERNAME=`whoami` +{% endhighlight %} If you have an existing GPG key, but it does not include your Apache email address, you can add your email address as described [in this Superuser.com posting](https://superuser.com/a/293283). Otherwise, create a new GPG key giving your -Apache email address. +Apache email address, using `gpg2 --gen-key` then `gpg2 --export-key $GPG_KEY > my-apache.key` and +`gpg2 --export-secret-key -a $GPG_KEY > my-apache.private.key` in the right directory (`~/.ssh` is a good one). Upload your GPG public key (complete with your Apache email address on it) to a public keyserver - e.g. run -`gpg2 --export --armor [email protected]` and paste it into the âsubmitâ box on http://pgp.mit.edu/ +`gpg2 --export --armor $GPG_KEY` and paste it into the âsubmitâ box on http://pgp.mit.edu/ -Look up your key fingerprint with `gpg2 --fingerprint [email protected]` - itâs the long sequence of hex numbers +Look up your key fingerprint with `gpg2 --fingerprint $GPG_KEY` - itâs the long sequence of hex numbers separated by spaces. Log in to [https://id.apache.org/](https://id.apache.org/) then copy-and-paste the fingerprint into âOpenPGP Public Key Primary Fingerprintâ. Submit. @@ -50,10 +58,12 @@ Now add your key to the `apache-dist-release-brooklyn/KEYS` file: {% highlight bash %} cd apache-dist-release-brooklyn (gpg2 --list-sigs [email protected] && gpg2 --armor --export [email protected]) >> KEYS -svn commit -m 'Update incubator/brooklyn/KEYS' +svn --username $SVN_USERNAME commit -m 'Update incubator/brooklyn/KEYS for $GPG_KEY' {% endhighlight %} -References: [Post on the general@incubator list](https://mail-archives.apache.org/mod_mbox/incubator-general/201410.mbox/%3CCAOGo0VawupMYRWJKm%2Bi%2ByMBqDQQtbv-nQkfRud5%2BV9PusZ2wnQ%40mail.gmail.com%3E) +References: +* [Post on the general@incubator list](https://mail-archives.apache.org/mod_mbox/incubator-general/201410.mbox/%3CCAOGo0VawupMYRWJKm%2Bi%2ByMBqDQQtbv-nQkfRud5%2BV9PusZ2wnQ%40mail.gmail.com%3E) +* [GPG cheatsheet](http://irtfweb.ifa.hawaii.edu/~lockhart/gpg/gpg-cs.html) Software packages @@ -63,14 +73,15 @@ The following software packages are required during the build. Make sure you hav - A Java Development Kit, version 1.7 - `maven` and `git` -- `xmlstarlet` is required by the release script to process version numbers in `pom.xml` files +- `xmlstarlet` is required by the release script to process version numbers in `pom.xml` files; + on mac, `port install xmlstarlet` should do the trick. - `zip` and `unzip` - `pinentry` for secure entry of GPG passphrases. If you are building remotely on a Linux machine, `pinentry-curses` is recommended; building on a mac, `port install pinentry-mac` is recommended. - `gnupg2`, and `gnupg-agent` if it is packaged separately (it is on Ubuntu Linux) -- `md5sum` and `sha1sum` - these are often present by default on Linux, but not on Mac. MacPorts provides these in the - package `md5sha1sum`. - +- `md5sum` and `sha1sum` - these are often present by default on Linux, but not on Mac; + `port install md5sha1sum` should remedy that. +- if `gpg` does not resolve (it is needed for maven), create an alias or script pointing at `gpg2 "$@"` Maven configuration ------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/48d06240/docs/website/developers/committers/release-process/release-version.md ---------------------------------------------------------------------- diff --git a/docs/website/developers/committers/release-process/release-version.md b/docs/website/developers/committers/release-process/release-version.md index 4f36d49..e43868b 100644 --- a/docs/website/developers/committers/release-process/release-version.md +++ b/docs/website/developers/committers/release-process/release-version.md @@ -51,6 +51,8 @@ Update the version on master The `master` branch will now need updating to refer to the next planned version. (This step is not required if making a "milestone" release or similar.) +The release notes should be cleared out and the version history augmented with the new version. + Example: {% highlight bash %} @@ -58,6 +60,15 @@ git checkout master ./release/change-version.sh BROOKLYN $OLD_MASTER_VERSION $NEW_MASTER_VERSION git add . # Now inspect the staged changes and ensure there are no surprises +{% endhighlight %} + +Open `docs/guide/misc/release-notes.md` and `docs/website/meta/versions.md` in your favourite editor and amend. +For release notes this means bumping the reference to the previous version in the "Backwards Compatibility" section +and putting some placeholder text elsewhere. + +Then: + +{% highlight bash %} git commit -m "Change version to $NEW_MASTER_VERSION" git push {% endhighlight %}
