Release management setup

The following instructions need to be done only once by new release managers, or when configuring a new machine for performing the releases. If those steps have already been done, jump directly to the Release Management page.

Directory layout

The steps described in the release management page assume the following directory layout. Some directories are SVN checkout, other are ordinary directories. Any other layout can be used. However in the later case, all relative paths in the release management page will need to be adjusted accordingly.

<any root directory for SIS>
├─ trunk
├─ branches
├─ tags
├─ non-free
│  └─ sis-epsg
├─ distribution
├─ release-test
│  └─ maven
└─ site

Create the above directory structure as below:

svn checkout https://svn.apache.org/repos/asf/sis/trunk
svn checkout https://svn.apache.org/repos/asf/sis/non-free
svn checkout https://svn.apache.org/repos/asf/sis/release-test
svn checkout https://svn.apache.org/repos/asf/sis/site/trunk site
svn checkout https://dist.apache.org/repos/dist/dev/sis distribution
mkdir branches
mkdir tags

Shell configuration

It is better for Unix shells to contain the following line in their initialization file (typically ~/.bashrc or ~/.profile, where ~ stands for the user's home directory):

export GPG_TTY=$(tty)

Generate GPG key

The releases have to be signed by public key cryptography signatures. Detailed instructions about why releases have to be signed are provided on the Release Signing page. The standard used is OpenPGP (Open Pretty Good Privacy), and a popular software implementation of that standard is GPG (GNU Privacy Guard). The OpenPGP instructions list out detailed steps on managing your keys. The following steps provide a summary:

Edit the ~/.gnupg/gpg.conf configuration file and add the following configuration options, or edit the existing values if any:

personal-digest-preferences SHA512
cert-digest-algo SHA512
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed

If a private key already exists for emails or other purposes, it may be a good idea to keep that key as the default one. Add or modify the following line in the gpg.conf file, replacing <previous_key_id> by the existing key identifier (a value like 621CC013):

default-key <previous_key_id>

Generate 4096 bits RSA key pair using the following command-line. GPG will prompts for various informations. The list below the command suggests some values, keeping in mind that the new key should be used only for signing Apache softwares - not for daily emails.

gpg --gen-key
  • Kind of key: RSA and RSA (default). Do not create DSA key.
  • Key size: 4096 bits.
  • Validity time: 0 (key does not expire).
  • Real name: the developer's name.
  • Email address: developer's email address at @apache.org.
  • Comment: "CODE SIGNING KEY".
  • Passphrase: please choose a strong one.

Verify the key information (replace Real Name by the above-cited developer's name, keeping quotes in the command below). Note the key identifier, which is a value like 74383E9D. This key identifier will be needed for the next steps.

gpg --list-sigs "Real Name"

Sends the public key to a keys server (replace <key_id> by the above-cited key identifier). The default GPG configuration sends the key to hkp://keys.gnupg.net. Note that while there is many key servers, most of them synchronize changes with each other, so a key uploaded to one should be disseminated to the rest.

gpg --send-key <key_id>

The key publication can be verified by going on the MIT server, then entering the developer's "Real Name" in the Search String field. It may take a few hours before the published key is propagated.

Generate a revocation certificate. This is not for immediate use, but generating the certificate now is a safety in case the passphrase is lost. Keep the revocation certificate in a safe place, preferably on a removable device.

gpg --output revocation_certificate.asc --gen-revoke <key_id>

Web of trust

Have the key signed by at least three Apache commiters. This can be done by executing the following commands on the machine of the other Apache commiter, where <key_to_use> is the identifier of the other commiter's key. Those operation should preferably be done in some event where the commiters can meet face-to-face. The other commiter should verify that the gpg --fingerprint command output matches the fingerprint of the key to sign.

gpg --recv-keys <key_id>
gpg --fingerprint <key_id>
gpg --default-key <key_to_use> --sign-key <key_id>
gpg --send-key <key_id>

The above-cited Release Signing page provides more instructions. Then, the signed public key shall be appended to the KEYS file on the SIS source code repository, then copied to the SIS distribution directory.

Maven Configuration & Nexus Setup

Detailed instructions are at Publishing Maven Artifacts. In summary, the developer needs to specify his Apache username and password (not the PGP passphrase) in his local ~/.m2 directory, and the GPG key identifier. First, if not already done, create a Maven master password:

mvn --encrypt-master-password <password>

The command will produce an encrypted version of the given password, something like {jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}. Store this password in the ~/.m2/settings-security.xml file like below:

<?xml version="1.0" encoding="UTF-8"?>
<settingsSecurity>
  <master>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}</master>
</settingsSecurity>

Then encrypt the Apache account password (not the PGP passphrase) like below:

mvn --encrypt-password <passphrase>

The command will produce an encrypted version of the password, something like {COQLCE6DU6GtcS5P=}. Cut-and-paste it in a section of the ~/.m2/settings.xml file like below, together with the PGP key name:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
...
  <servers>
    <server>
      <id>apache.releases.https</id>
      <username> <!-- your Apache username --> </username>
      <password>{COQLCE6DU6GtcS5P=}</password>
    </server>
   ...
  </servers>
  <profiles>
    <profile>
      <id>apache-release</id>
      <properties>
        <user.name> <!-- your Apache username --> </user.name>
        <gpg.keyname> <!-- the identifier of the GPG key generated in above steps --> </gpg.keyname>
      </properties>
    </profile>
  </profiles>
</settings>

Notes:

  • Do not store the PGP passphrase in the settings.xml file. We will use the gpg-agent instead, as described in the release management page.
  • In the <profile> section:
    • The <user.name> property can be omitted if the Apache user name matches the user name on the local operating system.
    • The <gpg.keyname> property can be omitted if GPG contains only one private key.
    • The whole <profile> section can be omitted if the two above-cited properties are omitted.