1# Release Process: 2This document describes the general process that maintainers must follow when making a release of the `tpm2-tss` libraries. 3 4# Version Numbers 5Our releases will follow the semantic versioning scheme. 6You can find a thorough description of this scheme here: [http://semver.org/](http://semver.org/) 7In short, this scheme has 3 parts to the version number: A.B.C 8 9* A is the 'major' version, incremented when an API incompatible change is made 10* B is the 'minor' version, incremented when an API compatible change is made 11* C is the 'micro' version, incremented for bug fix releases 12Please refer to the [Semantic Versioning](http://semver.org/) website for the authoritative description. 13 14## Version String 15The version string is set for the rest of the autotools bits by autoconf. 16Autoconf gets this string from the `AC_INIT` macro in the configure.ac file. 17Once you decide on the next version number (using the scheme above) you must set it manually in configure.ac. 18The 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. 19 20## Release Candidates 21In the run up to a release the maintainers may create tags to identify progress toward the release. 22In these cases we will append a string to the release number to indicate progress using the abbreviation `rc` for 'release candidate'. 23This string will take the form of `_rcX`. 24We append an incremental digit `X` in case more than one release candidate is necessary to communicate progress as development moves forward. 25 26# Static Analysis 27Before a release is made the `coverity_scan` branch must be updated to the point in git history where the release will be made from. 28This branch must be pushed to github which will cause the travis-ci infrastructure to run an automated coverity scan. 29The results of this scan must be dispositioned by the maintainers before the release is made. 30 31# Git Tags 32When a release is made a tag is created in the git repo identifying the release by the [version string](#Version String). 33The tag should be pushed to upstream git repo as the last step in the release process. 34**NOTE** tags for release candidates will be deleted from the git repository after a release with the corresponding version number has been made. 35**NOTE** release (not release candidate) tags should be considered immutable. 36 37## Signed tags 38Git supports GPG signed tags and for releases after the `1.1.0` release will have tags signed by a maintainer. 39For details on how to sign and verify git tags see: https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work. 40 41# Release tarballs 42We use the git tag as a way to mark the point of the release in the projects history. 43We do not however encourage users to build from git unless they intend to modify the source code and contribute to the project. 44For the end user we provide release "tarballs" following the GNU conventions as closely as possible. 45 46To make a release tarball use the `distcheck` make target. 47This target includes a number of sanity checks that are extremely helpful. 48For more information on `automake` and release tarballs see: https://www.gnu.org/software/automake/manual/html_node/Dist.html#Dist 49 50## Hosting Releases on Github 51Github automagically generates a page in their UI that maps git tags to 'releases' (even if the tag isn't for a release). 52Additionally they support hosting release tarballs through this same interface. 53The release tarball created in the previous step must be posted to github using the release interface. 54Additionally this tarball must be accompanied by a detached GPG signature. 55The Debian wiki has an excellent description of how to post a signed release to Github here: https://wiki.debian.org/Creating%20signed%20GitHub%20releases 56**NOTE** release candidates must be taken down after a release with the corresponding version number is available. 57 58## Signing Release Tarballs 59Signatures must be generated using the `--detach-sign` and `--armor` options to the `gpg` command: 60``` 61$ gpg --detach-sign --armor tpm2-tss-X.Y.Z.tar.gz 62``` 63 64## Verifying Signatures 65Verifying the signature on a release tarball requires the project maintainers public keys be installed in the GPG keyring of the verifier. 66With both the release tarball and signature file in the same directory the following command will verify the signature: 67``` 68$ gpg --verify tpm2-tss-X.Y.Z.tar.gz.asc 69``` 70 71## Signing Keys 72The GPG keys used to sign a release tag and the associated tarball must be the same. 73Additionally they must: 74* belong to a project maintainer 75* be discoverable using a public GPG key server 76* be associated with the maintainers github account (https://help.github.com/articles/adding-a-new-gpg-key-to-your-github-account/) 77 78# Announcements 79Release candidates and proper releases should be announced on the 01.org TPM2 mailing list: https://lists.01.org/postorius/lists/tpm2.lists.01.org/. 80This 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. 81 82# Maintainance 83The most recent minor releases will receive bug fixes and bug fix releases. 84Additionally the latest major release will receive bug fixes for another year after release. 85 86# Release schedule 87The project aims for 3 releases per year; early spring, summer, late fall. 88Whether a release is a major or minor release depends on whether an API/ABI break occurs (see [Semantic Versioning](http://semver.org/)). 89