# Release Process:
This document describes the general process that maintainers must follow when
making a release of the `tpm2-tss-engine` library and cli-tool.

# Milestones
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.

# Version Numbers
This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

In summary: Given a version number MAJOR.MINOR.PATCH, increment the:
1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
3. 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.

## Version String
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.

## Release Candidates
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.

# 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.

# Git Tags
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.

## Signed tags
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.

# Release tarballs
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

## Hosting Releases on Github
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.

## Signing Release Tarballs
Signatures must be generated using the `--detach-sign` and `--armor` options to
the `gpg` command.

## Verifying Signatures
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
```

## Signing Keys
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/)

# Announcements
Release candidates and proper releases should be announced on the mailing list:
  - https://lists.linuxfoundation.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.