Skip to content

HOWTO-RELEASE.md

Latest commit

 

History

History
106 lines (73 loc) · 4.29 KB

HOWTO-RELEASE.md

File metadata and controls

106 lines (73 loc) · 4.29 KB

Release Instructions

This is a guide for Couchbase employees. It describes how to cut a release of this project and publish it to the Maven Central Repository.

Prerequisites

You will need:

  • The gpg command-line program and a PGP key. Mac users, grab gpg from https://gpgtools.org and enjoy this setup guide. Generate a PGP key with your couchbase.com email address and uploaded it to a public keyserver. For bonus points, have a few co-workers sign your key.
  • To tell git about your signing key: git config --global user.signingkey DEADBEEF (replace DEADBEEF with the id of your PGP key).
  • A Sonatype account authorized to publish to the com.couchbase namespace.
  • A ~/.m2/settings.xml file with a User Token. To generate a token, go to https://oss.sonatype.org and log in with your Sonatype account. Click on your username (upper right) and select "Profile". From the drop-down menu, select "User Token". Press "Access User Token" to see a snippet of XML with server credentials. Copy and paste this XML into the servers section of your Maven settings, replacing ${server} with ossrh.

At a minimum, your ~/.m2/settings.xml should look something like:

<settings>
  <servers>
    <server>
      <id>ossrh</id>
      <username>xxxxxxxx</username>
      <password>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</password>
    </server>
  </servers>
</settings>

All set? In that case...

Let's do this!

Start by running mvn clean verify -Prelease to make sure the project builds successfully, artifact signing works, and the tests pass. If an integration test fails (and if you're okay with that), add -DskipITs to the Maven command line to skip integration tests. When you're satisfied with the test results, it's time to...

Bump the project version number

  1. Edit pom.xml and remove the -SNAPSHOT prefix from the version string.
  2. Edit README.md and bump the version numbers. There may be references to the next snapshot release, so remember to edit those too.
  3. Commit these changes, with message "Prepare x.y.z release" (where x.y.z is the version you're releasing).

Tag the release

Run the command git tag -s x.y.z (where x.y.z is the release version number).

Use the previous version's tag message (e.g. git show 0.11.0) as a template for the new version's tag message.

Don't push the tag right away, though. Wait until the release is successful and you're sure there will be no more changes. Otherwise it can be a pain to remove an unwanted tag from Gerrit.

Go! Go! Go!

Here it is, the moment of truth. When you're ready to deploy to the Maven Central Repository:

mvn clean deploy -Prelease

Alternatively, if you prefer to inspect the staging repository and complete the release manually, you can use the stage profile instead of the release profile:

mvn clean deploy -Pstage

Remember, you can add -DskipITs to either command to skip integration tests if appropriate.

Whew, you did it! Or the build failed and you're looking at a cryptic error message, in which case you might want to check out the Troubleshooting section below.

If the release succeeded, now's the time to publish the tag:

git push origin x.y.z

Prepare for next dev cycle

Increment the version number in pom.xml and restore the -SNAPSHOT suffix. Commit and push to Gerrit. Breathe in. Breathe out.

Troubleshooting

  • Take another look at the Prerequisites section. Did you miss anything?
  • This gist has some tips for making git and gpg play nice together.
  • If you see Deployment failed: repository element was not specified in the POM inside distributionManagement element it probably means you forgot to remove the -SNAPSHOT suffix from the version, and Maven is complaining because there's no repository configured for snapshots.
  • If deployment fails because the artifacts are missing PGP signatures, make sure your Maven command line includes -Prelease (or -Pstage) when running mvn deploy. Note that this is a profile so it's specified with -P.