website/developers/committers/release-process/prerequisites.md - brooklyn-docs - Git at Google

 ---
 layout: website-normal
 title: Release Prerequisites
 navgroup: developers
 ---

 Subversion repositories for release artifacts
 ---------------------------------------------

 Apache releases are posted to dist.apache.org, which is a Subversion repository.

 We have two directories here:

 - https://dist.apache.org/repos/dist/release/brooklyn - this is where PMC approved releases go. Do not upload
   here until we have a vote passed on dev@brooklyn. Check out this folder and name it
   `apache-dist-release-brooklyn`
 - https://dist.apache.org/repos/dist/dev/brooklyn - this is where releases to be voted on go. Make the release
   artifact, and post it here, then post the [VOTE] thread with links here. Check out this folder and name it
   `apache-dist-dev-brooklyn`.

 Example:

 {% highlight bash %}
 svn co https://dist.apache.org/repos/dist/release/brooklyn apache-dist-release-brooklyn
 svn co https://dist.apache.org/repos/dist/dev/brooklyn apache-dist-dev-brooklyn
 {% endhighlight %}

 When working with these folders, **make sure you are working with the correct one**, otherwise you may be publishing
 pre-release software to the global release mirror network!


 Software packages
 -----------------

 The following software packages are required during the build. Make sure you have them installed.

 - A Java Development Kit, version 1.8
 - `maven` and `git`
 - Go Language 1.6 - usually provided by the `golang` package on popular distributions
 - The `rpmbuild` command - usually provided by the `rpm` package on popular distributions
 - `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`
 - `gnupg2`, and `gnupg-agent` if it is packaged separately (it is on Ubuntu Linux)
 - `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.
 - `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 "$@"`
 - the `mmv` command (usually in a package named `mmv`) will help with the final steps of the release process


 GPG keys
 --------

 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 %}
 ASF_USERNAME=`whoami`
 GPG_KEY=$ASF_USERNAME@apache.org
 SVN_USERNAME=$ASF_USERNAME
 {% 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, 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 $GPG_KEY` and paste it into the “submit” box on http://pgp.mit.edu/

 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.

 Now add your key to the `apache-dist-release-brooklyn/KEYS` file:

 {% highlight bash %}
 cd apache-dist-release-brooklyn
 (gpg2 --list-sigs $ASF_USERNAME@apache.org && gpg2 --armor --export $ASF_USERNAME@apache.org) >> KEYS
 svn --username $SVN_USERNAME --no-auth-cache commit -m "Update 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)
 * [GPG cheatsheet](http://irtfweb.ifa.hawaii.edu/~lockhart/gpg/gpg-cs.html)

 We recommend the use of the `gpg-agent`, as the release process invokes gpg to sign a large number of artifacts, one at
 a time. The agent stores its configuration in `~/.gnupg/gpg-agent.conf`. A sample configuration is shown below; it uses
 the Mac OSX `pinentry-mac` program which can be obtained through MacPorts or other sources. For other platforms you will
 need to change this; sometimes you can omit it completely and your OS will pick a suitable alternative. The following
 two lines cause your passphrase to be cached in memory for a limited period; it will expire from the cache 30 minutes
 after it was most recently accessed, or 4 hours after it was first cached.

 ~~~
 pinentry-program /Applications/MacPorts/pinentry-mac.app/Contents/MacOS/pinentry-mac
 default-cache-ttl 1800
 max-cache-ttl 14400
 ~~~

 If you experience trouble with PGP subsequently (when running maven):

 * See [GnuPG/Pinentry Enigmail debugging](https://www.enigmail.net/support/gnupg2_issues.php) for tips on diagnosing gpg-agent communication (from the process to this agent and from this agent to the pinentry program)
 * See [GnuPG Agent Options](https://www.gnupg.org/documentation/manuals/gnupg/Agent-Options.html) for extended gpg-agent debug


 Maven configuration
 -------------------

 The release will involve uploading artifacts to Apache's Nexus instance - therefore you will need to configure your
 Maven install with the necessary credentials.

 You will need to add something like this to your `~/.m2/settings.xml` file:

 {% highlight xml %}
 <?xml version="1.0"?>
 <settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
           xmlns="http://maven.apache.org/SETTINGS/1.1.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

     <!-- ... -->

     <servers>

         <!-- ... -->

         <!-- Required for uploads to Apache's Nexus instance. These are LDAP credentials - the same credentials you
            - would use to log in to Git and Jenkins (but not JIRA) -->
         <server>
             <id>apache.snapshots.https</id>
             <username>xxx</username>
             <password>xxx</password>
         </server>
         <server>
             <id>apache.releases.https</id>
             <username>xxx</username>
             <password>xxx</password>
         </server>

         <!-- ... -->

     </servers>

     <!-- ... -->

 </settings>
 {% endhighlight %}
	---
	layout: website-normal
	title: Release Prerequisites
	navgroup: developers
	---

	Subversion repositories for release artifacts
	---------------------------------------------

	Apache releases are posted to dist.apache.org, which is a Subversion repository.

	We have two directories here:

	- https://dist.apache.org/repos/dist/release/brooklyn - this is where PMC approved releases go. Do not upload
	here until we have a vote passed on dev@brooklyn. Check out this folder and name it
	`apache-dist-release-brooklyn`
	- https://dist.apache.org/repos/dist/dev/brooklyn - this is where releases to be voted on go. Make the release
	artifact, and post it here, then post the [VOTE] thread with links here. Check out this folder and name it
	`apache-dist-dev-brooklyn`.

	Example:

	{% highlight bash %}
	svn co https://dist.apache.org/repos/dist/release/brooklyn apache-dist-release-brooklyn
	svn co https://dist.apache.org/repos/dist/dev/brooklyn apache-dist-dev-brooklyn
	{% endhighlight %}

	When working with these folders, make sure you are working with the correct one, otherwise you may be publishing
	pre-release software to the global release mirror network!


	Software packages
	-----------------

	The following software packages are required during the build. Make sure you have them installed.

	- A Java Development Kit, version 1.8
	- `maven` and `git`
	- Go Language 1.6 - usually provided by the `golang` package on popular distributions
	- The `rpmbuild` command - usually provided by the `rpm` package on popular distributions
	- `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`
	- `gnupg2`, and `gnupg-agent` if it is packaged separately (it is on Ubuntu Linux)
	- `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.
	- `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 "$@"`
	- the `mmv` command (usually in a package named `mmv`) will help with the final steps of the release process


	GPG keys
	--------

	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 %}
	ASF_USERNAME=`whoami`
	GPG_KEY=$ASF_USERNAME@apache.org
	SVN_USERNAME=$ASF_USERNAME
	{% 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, 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 $GPG_KEY` and paste it into the “submit” box on http://pgp.mit.edu/

	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.

	Now add your key to the `apache-dist-release-brooklyn/KEYS` file:

	{% highlight bash %}
	cd apache-dist-release-brooklyn
	(gpg2 --list-sigs $ASF_USERNAME@apache.org && gpg2 --armor --export $ASF_USERNAME@apache.org) >> KEYS
	svn --username $SVN_USERNAME --no-auth-cache commit -m "Update 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)
	* [GPG cheatsheet](http://irtfweb.ifa.hawaii.edu/~lockhart/gpg/gpg-cs.html)

	We recommend the use of the `gpg-agent`, as the release process invokes gpg to sign a large number of artifacts, one at
	a time. The agent stores its configuration in `~/.gnupg/gpg-agent.conf`. A sample configuration is shown below; it uses
	the Mac OSX `pinentry-mac` program which can be obtained through MacPorts or other sources. For other platforms you will
	need to change this; sometimes you can omit it completely and your OS will pick a suitable alternative. The following
	two lines cause your passphrase to be cached in memory for a limited period; it will expire from the cache 30 minutes
	after it was most recently accessed, or 4 hours after it was first cached.

	~~~
	pinentry-program /Applications/MacPorts/pinentry-mac.app/Contents/MacOS/pinentry-mac
	default-cache-ttl 1800
	max-cache-ttl 14400
	~~~

	If you experience trouble with PGP subsequently (when running maven):

	* See [GnuPG/Pinentry Enigmail debugging](https://www.enigmail.net/support/gnupg2_issues.php) for tips on diagnosing gpg-agent communication (from the process to this agent and from this agent to the pinentry program)
	* See [GnuPG Agent Options](https://www.gnupg.org/documentation/manuals/gnupg/Agent-Options.html) for extended gpg-agent debug


	Maven configuration
	-------------------

	The release will involve uploading artifacts to Apache's Nexus instance - therefore you will need to configure your
	Maven install with the necessary credentials.

	You will need to add something like this to your `~/.m2/settings.xml` file:

	{% highlight xml %}
	<?xml version="1.0"?>
	<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
	xmlns="http://maven.apache.org/SETTINGS/1.1.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

	<!-- ... -->

	<servers>

	<!-- ... -->

	<!-- Required for uploads to Apache's Nexus instance. These are LDAP credentials - the same credentials you
	- would use to log in to Git and Jenkins (but not JIRA) -->
	<server>
	<id>apache.snapshots.https</id>
	<username>xxx</username>
	<password>xxx</password>
	</server>
	<server>
	<id>apache.releases.https</id>
	<username>xxx</username>
	<password>xxx</password>
	</server>

	<!-- ... -->

	</servers>

	<!-- ... -->

	</settings>
	{% endhighlight %}