Testing a Source Release

Testing a Source Release

Apache Annotator (incubating) follows Apache Software Foundation policy¹ for releases. This page documents the process for testing releases.

Obtaining a Release Candidate

Create a directory to store the files and set it as the current working directory:

$ mkdir /tmp/annotator
$ cd /tmp/annotator

Download the release candidate tarball and its associated signatures and checksums:

$ curl -O https://dist.apache.org/repos/dist/dev/incubator/annotator/source/X.Y.Z/rc.N/apache-annotator-X.Y.Z-rc.N-incubating.tar.gz
$ curl -O https://dist.apache.org/repos/dist/dev/incubator/annotator/source/X.Y.Z/rc.N/apache-annotator-X.Y.Z-rc-incubating.N.tar.gz.asc
$ curl -O https://dist.apache.org/repos/dist/dev/incubator/annotator/source/X.Y.Z/rc.N/apache-annotator-X.Y.Z-rc.N-incubating.tar.gz.sha256
$ curl -O https://dist.apache.org/repos/dist/dev/incubator/annotator/source/X.Y.Z/rc.N/apache-annotator-X.Y.Z-rc.N-incubating.tar.gz.sha512

Substitute cURL for any tool of your choice, such as wget.

Verifying the Authenticity of a Release Candidate

Release managers sign the releases and publish PGP public keys for verifying the signatures. Import the keys into the local keychain:

$ curl -L https://apache.org/dist/incubator/annotator/KEYS | gpg --import -

Verify the release signature:

$ gpg --verify apache-annotator-*.tar.gz.asc

The output of this command should say that the signature is good and list the name, email address, and key of the release manager. If anything looks incorrect, please notify the mailing list. The release managers are aware that their keys are not strongly connected to a web of trust and are working to resolve that in the future.

Verify the release checksums:

$ sha256sum --check apache-annotator-*.tar.gz.sha256
$ sha512sum --check apache-annotator-*.tar.gz.sha512

Verifying the Contents of a Release Candidate

The Apache Annotator (incubating) project distributes release tarballs that are shallow clones of the git source control repository, making it easy to verify that the release contents contain the correct code.

Unpack the tarball and change the current working directory to be that of the unpacked source:

$ tar xzf apache-annotator-X.Y.Z-rc.N-incuabting.tar.gz
$ cd apache-annotator-X.Y.Z-incubating

Check that the current HEAD of the git repository is tagged:

$ git describe

The output should say "vX.Y.Z-rc.N" exactly, with no additional suffixes.

Check that the remote repository is correctly configured:

$ git remote show origin

The output should show the repository as https://github.com/apache/incubator-annotator.

Check that the tag matches the tag from the remote repository by fetching it:

$ get fetch origin tag vX.Y.Z-rc.N

There should be no output if the local tag matches the remote tag.

Check that the working directory is clean, containing only the files under version control:

$ git status --ignored

The output should include "nothing to commit, working tree clean".

Verifying the Correctness of the Source Release

Source releases should build and pass all automated tests:

$ make check

Inspect the output for any errors or failures and bring any issues to the mailing list.