Project release process

Responsibilities

The release process is performed by the project owner. Every project has a primary owner and a backup owner.

Approvals

The project owner approves alpha and beta releases. Andrew approves final releases.

Release frequency

We release any time changes are made to a project that require integration testing with other projects.

Release versioning

We use semantic versioning, which creates version numbers with the format MAJOR.MINOR[.PATCH]. Increment:

• The MAJOR version when you make incompatible API changes.
• The MINOR version when you add functionality in a backwards-compatible manner.
• The PATCH version when you make backwards-compatible bug fixes (optional).

Releasing Java projects

Java semantic versioning

Maven supports semantic versioning, and adds to it a convention for specifying alpha, beta and pre-release version. Version numbers have the format MAJOR.MINOR[.PATCH][-TYPE-ATTEMPT]. The last part is optional and only used to identify that the version is not necessarily final. We use the following type values:

• Alpha: the project is not yet feature complete for the planned final release.
• Beta: the project is feature complete but not yet ready for final release.

ATTEMPT is incremented for each Alpha and Beta release.

Java release tools

We use the maven:release plugin as follows:

1. Ensure the README is updated. For final releases, describe changes since the last final release.
2. Commit all changes. The process will fail if there is any uncommitted code in your repo.
3. Run mvn clean install to make sure the project builds successfully.
4. Run mvn release:prepare. Answer the prompts for the release version number and the next SNAPSHOT release.
5. Run mvn release:perform to publish the release to Maven Central's staging repository (requires login). The artifact will be available in Nexus under "Build Promotion" then "Staging Repositories" on the left-hand side of your browser window. The artifact will be in a temporary repository with a name containing your artifact's group id.
6. Inspect the artifact in the staging repository.
7. Select the repository containing your artifact, and click the Release button at the top of the repository list to release the artifact.

The release:perform step requires some pre-configuration:

1. Install and configure Gnu Privacy Guard (GPG) on your workstation.
2. Create a server profile in ~/.m2/settings.xml with your Maven Central credentials as follows:

<server>
    <id>ossrh</id>
    <username>your username</username>
    <password>you password</password>
</server>

3. Create a profile in ~/.m2/settings.xml with your GPG credentials as follows:

<profile>
    <id>ossrh</id>
    <activation>
        <activeByDefault>true</activeByDefault>
    </activation>
    <properties>
        <gpg.executable>gpg</gpg.executable>
        <gpg.passphrase>your passphrase</gpg.passphrase>
    </properties>
</profile>

3. All set!

Releasing web client projects

These instructions are for any project that contains only web pages, javascript, CSS, etc.

Web client semantic versioning

Follow the same convention as for Java, described above.

Web client release tools

1. Ensure the README is updated. For final releases, describe changes since the last final release.
2. Commit all changes.
3. Tag the commit you want to release with the version number. The name of the tag should contain just the version number.

The provisioning project will pull a release directly from GitHub using its APIs, which automatically bundle the repository as an archive file.

Releasing Python projects

Python project semantic versioning

The version is specified in the setup.py file according to the convention described in PEP 440.

Python project release tools

1. Ensure the README is updated. For final releases, describe changes since the last final release.
2. Update the setup.py with the latest release number.
3. Commit all changes.
4. Tag the commit you want to release with the version number. The name of the tag should contain just the version number.

The provisioning project will pull a release directly from GitHub using its APIs, which automatically bundle the repository as an archive file.

After the release

If you have created a final major release for the first time, make sure that you create a branch called release-branch starting from the commit immediately after the one tagged with the release version. For Java code released using maven, the commit comment will be something like [maven-release plugin] prepare for next development iteration. All minor and patch releases with the same major release number are developed on the release-branch. Synchronized those changes with upstream master as appropriate.