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.N-incubating.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

Unpack the tarball:

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

Clone the upstream source at the release candidate tag:

$ git clone --single-branch --branch vX.Y.Z-rc.N https://github.com/apache/incubator-annotator.git repo

Compare the contents of the tarball and the repository:

$ diff -r apache-annotator-X.Y.Z-incubating repo

The output should show several files that are only in the repository and not in the distribution. If there is any doubt as to the correctness of this result, ask for clarification on the vote thread.

Verifying the License Notifications of the Source Release

Releases should include LICENSE and NOTICE files that follow the conventions of Apache Software Foundation projects. As the project is still under incubation, releases should also contain a DISCLAIMER-WIP file. Despite the work-in-progress disclaimer, it is the intention of the project to fully adhere to Apache Software Foundation policy.

If you'd like to help ensure that the project is adhering to policy by using the Apache Rat² tool to check license headers (replacing the path to the Apache Rat file as appropriate):

$ java -jar ~/.local/share/apache-rat-0.13.jar -E repo/.ratignore -d apache-annotator-X.Y.Z-incubating

Raise any issues or questions on the mailing list.

Verifying the Correctness of the Source Release

Source releases should build and pass all automated tests:

$ cd apache-annotator-X.Y.Z-incubating
$ make check

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

Finishing Up

Delete the /tmp/annotator directory to remove all files that result from following these instructions. Submit your vote on the mailing list thread to approve or disapprove of the release. Voting participation is greatly appreciated by the community. Thank you!