Release Process

This document describes the overall release process of the tpm2-tools project.

Milestones

All releases should have a milestone used to track the release. If the release version is not known, as covered in 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 for details.

Release Lifecycle

All tpm2-tools project releases before 4.0 is considered legacy and is or will be reaching end of life. Releases greater than 4.0 will always will be backwards compatible.

Release will be conducted off the master branch and feature/bugfix only releas branches can be created off of master and maintained as needed. The majority of development will occur on master with tagged release numbers following semver.org recommendations. This page explicitly does not formalize an LTS support timeline, and that is intentional. The release schedules and required features are driven by community involvement and needs. However, milestones will be created to outline the goals, bugs, issues and timelines of the next release.

End Of Life versions

Release Information

Releases shall be tagged following semantic version guidelines found at: - http://semver.org/

The general release process will be one of two models:

  • Tag releases off of branch master.
  • Tag releases off of a release specific branch.
  • Release specific branch names can be for long-running major versions, IE 3.1, 3.2, 3.3, etc. and SHALL be named <major-version>.X.
  • Release specific branch names can be for long-running minor versions, IE 3.1.1, 3.1.2, etc. and SHALL be named <major-version>.<minor-version>.X.

Release candidates will be announced on the mailing list. When a RC has gone 1 week without new substantive changes, a release will be conducted. Substantive changes are generally not editorial in nature and they do not contain changes to the CI system. Substantive changes are changes to the man-pages, code or tests.

When a release is cut, the process is the same as a Release Candidate (RC), with the exception that it is not marked as "pre-release" on GitHub. The release notes should include everything from the last release to the latest release.

CHANGELOG Update

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.

The commit that updated the CHANGELOG entry will be tagged as the final release.

For a final release, change the version to the final release version (i.e: 3.0.5-rc3 -> 3.0.5) and update the date. The commit for this change will be tagged as the release version.

Testing

The tools code MUST pass the Github Actions CI testing and have a clean Coverity scan result performed on every release. The CI testing not only tests for valid outputs, but also runs tests uses clang's ASAN feature to detect memory corruption issues. - BUG: Reconfigure Coverity: https://github.com/tpm2-software/tpm2-tools/issues/1727

Release Checklist

The steps, in order, required to make a release.

  • Ensure current HEAD is pointing to the last commit in the release branch.

  • Ensure Github Actions CI has conducted a passing build of HEAD.

  • Update version and date information in CHANGELOG.md and commit per the CHANGELOG Update instructions.

  • Create a signed tag for the release. Use the version number as the title line in the tag commit message and use the CHANGELOG.md contents for that release as the body. bash git tag -s <tag-name>

  • Build a tarball for the release and check the dist tarball. Note: The file name of the tarball should include a match for the git tag name. bash make distcheck

  • Generate a detached signature for the tarball. bash gpg --armor --detach-sign <tarball>

  • Push both the current git HEAD (should be the CHANGELOG edit) and tag to the release branch. bash git push origin HEAD:<release-branch> git push origin <tag-name>

  • Verify that the Github Actions CI build passes. Note: Github Actions CI will have two builds, one for the push to master and one for the tag push. Both should succeed.

  • Create a release on Github, using the <release-tag> uploaded. If it is a release candidate, ensure you check the "pre-release" box on the GitHub UI. Use the CHANGELOG.md contents for that release as the message for the GitHub release. Add the dist tarball and signature file to the release.

  • Update the dependency-matrix ensuring that the CI is building against a released version of:

  • tpm2-abrmd
  • tpm2-tss

Configuration can be modified via docker-prelude.sh.

  • After the release (not a release candidate) add a commit to master updating the News section of the README to point to the latest release.

  • Send announcement on mailing list.

Historical Version Information

Versions after v1.1.0 will no longer have the "v" prefix. Autoconf now sets the VERSION #define based on the output of git describe. See commit 2e8a07bc for the details.

Version tags after v1.1.0 shall be signed.

Verifying git signature

Valid known public keys can be reached by referencing the annotated tags listed below:

Tag Fingerprint
idesai-pub 6313e6dc41aafc315a8760a414986f6944b1f72b
william-roberts-pub 5b482b8e3e19da7c978e1d016de2e9078e1f50c1
javier-martinez-pub D75ED7AA24E50CD645C6F457C751E590D63F3D69
joshua-lock-pub 5BEC526CE3A61CAF07E7A7DA49BCAE5443FFFC34
ajay-kish-pub 6f72a30eea41b9b548570ad20d0db2b265493e29
juergen-repp-pub 7A8F470DA9C8B2CACED1DBAAF1B152D9441A2563
andreas-fuchs-pub D533275B0123D0A679F51FF48F4F9A45D7FFEE74

or via a PGP public keyring server like: - http://keyserver.pgp.com/vkd/GetWelcomeScreen.event

Import the key into your keyring:

$ git show [annotated-tag-name] | gpg --import

Example:

$ git show william-roberts-pub | gpg --import

Verify the release tag:

$ git tag --verify [signed-tag-name]

Local Release Configuration

Below you will find information how to configure your machine locally to conduct releases.

Signing Key Setup

Signing keys should have these four properties going forward: - belong to a project maintainer. - be discoverable using a public GPG key server. - be associated with the maintainers GitHub account. - be discoverable via an annotated tag within the repository itself.

Ensure you have a key set up:

$ gpg --list-keys

If you don't generate one:

$ gpg --gen-key

Add that key to the gitconfig:

git config user.signingkey [gpg-key-id]

Make sure that key is reachable as an object in the repository:

gpg -a --export [gpg-key-id] | git hash-object -w --stdin [object SHA]
git tag -a [your-name-here]-pub [object SHA]

Make sure you push the tag referencing your public key:

git push origin [your-name-here]-pub

Make sure you publish your key by doing: - http://keyserver.pgp.com/vkd/GetWelcomeScreen.event - Select "Publish your key". - Select "Key block" - Copy and paste the output of gpg --armor --export <key-id> - Validate your email account.

After that, you can sign tags:

git tag --sign [signed-tag-name]