This document describes the general process that maintainers must follow when
making a release of the tpm2-tss-engine library and cli-tool.
All releases should have a milestone used to track the release. If the release version is not known, as covered in [Version Numbers](#Version Numbers), then an "x" may be used for the unknown number, or the generic term "next" may be used. The description field of the milestone will be used to record the CHANGELOG for that release. See [CHANGELOG Update](#CHANGELOG Update) for details.
This project adheres to Semantic Versioning.
In summary: Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- PATCH version when you make backwards-compatible bug fixes. Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
The version string is set for the rest of the autotools bits by autoconf.
Autoconf gets this string from the AC_INIT macro in the configure.ac file.
Once you decide on the next version number (using the scheme above) you must set
it manually in configure.ac. The version string must be in the form A.B.C
where A, B and C are integers representing the major, minor and micro
components of the version number.
In the run up to a release the maintainers may create tags to identify progress
toward the release. In these cases we will append a string to the release number
to indicate progress using the abbreviation rc for 'release candidate'. This
string will take the form of -rcX. We append an incremental digit X in case
more than one release candidate is necessary to communicate progress as
development moves forward.
Before tagging the repository with the release version, the maintainer MUST update the CHANGELOG file with the contents from the description field from the corresponding release milestone and update any missing version string details in the CHANGELOG and milestone entry.
When a release is made a tag is created in the git repo identifying the release by the [version string](#Version String). The tag should be pushed to upstream git repo as the last step in the release process. NOTE tags for release candidates will be deleted from the git repository after a release with the corresponding version number has been made. NOTE release (not release candidate) tags should be considered immutable.
Git supports GPG signed tags and releases will have tags signed by a maintainer. For details on how to sign and verify git tags see: https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work.
We use the git tag as a way to mark the point of the release in the projects history. We do not however encourage users to build from git unless they intend to modify the source code and contribute to the project. For the end user we provide release tarballs following the GNU conventions as closely as possible.
To make a release tarball use the distcheck make target.
This target includes a number of sanity checks that are extremely helpful.
For more information on automake and release tarballs see:
https://www.gnu.org/software/automake/manual/html_node/Dist.html#Dist
Github automagically generates a page in their UI that maps git tags to 'releases' (even if the tag isn't for a release). Additionally they support hosting release tarballs through this same interface. The release tarball created in the previous step must be posted to github using the release interface. Additionally, this tarball must be accompanied by a detached GPG signature. The Debian wiki has an excellent description of how to post a signed release to Github here: https://wiki.debian.org/Creating%20signed%20GitHub%20releases NOTE release candidates must be taken down after a release with the corresponding version number is available.
Signatures must be generated using the --detach-sign and --armor options to
the gpg command.
Verifying the signature on a release tarball requires the project maintainers public keys be installed in the GPG keyring of the verifier. With both the release tarball and signature file in the same directory the following command will verify the signature:
$ gpg --verify tpm2-tss-engine-X.Y.Z.tar.gz.asc
The GPG keys used to sign a release tag and the associated tarball must be the same. Additionally they must:
- belong to a project maintainer
- be discoverable using a public GPG key server
- be associated with the maintainers github account (https://help.github.com/articles/adding-a-new-gpg-key-to-your-github-account/)
Release candidates and proper releases should be announced on the 01.org TPM2 mailing list: https://lists.01.org/mailman/listinfo/tpm2. This announcement should be accompanied by a link to the release page on Github as well as a link to the CHANGELOG.md accompanying the release.