1<a id="top"></a> 2# How to release 3 4When enough changes have accumulated, it is time to release new version of Catch. This document describes the process in doing so, that no steps are forgotten. Note that all referenced scripts can be found in the `scripts/` directory. 5 6## Necessary steps 7 8These steps are necessary and have to be performed before each new release. They serve to make sure that the new release is correct and linked-to from the standard places. 9 10 11### Testing 12 13All of the tests are currently run in our CI setup based on TravisCI and 14AppVeyor. As long as the last commit tested green, the release can 15proceed. 16 17 18### Incrementing version number 19 20Catch uses a variant of [semantic versioning](http://semver.org/), with breaking API changes (and thus major version increments) being very rare. Thus, the release will usually increment the patch version, when it only contains couple of bugfixes, or minor version, when it contains new functionality, or larger changes in implementation of current functionality. 21 22After deciding which part of version number should be incremented, you can use one of the `*Release.py` scripts to perform the required changes to Catch. 23 24This will take care of generating the single include header, updating 25version numbers everywhere and pushing the new version to Wandbox. 26 27 28### Release notes 29 30Once a release is ready, release notes need to be written. They should summarize changes done since last release. For rough idea of expected notes see previous releases. Once written, release notes should be added to `docs/release-notes.md`. 31 32 33### Commit and push update to GitHub 34 35After version number is incremented, single-include header is regenerated and release notes are updated, changes should be committed and pushed to GitHub. 36 37 38### Release on GitHub 39 40After pushing changes to GitHub, GitHub release *needs* to be created. 41Tag version and release title should be same as the new version, 42description should contain the release notes for the current release. 43Single header version of `catch.hpp` *needs* to be attached as a binary, 44as that is where the official download link links to. Preferably 45it should use linux line endings. All non-bundled reporters (Automake, TAP, 46TeamCity, SonarQube) should also be attached as binaries, as they might be 47dependent on a specific version of the single-include header. 48 49Since 2.5.0, the release tag and the "binaries" (headers) should be PGP 50signed. 51 52#### Signing a tag 53 54To create a signed tag, use `git tag -s <VERSION>`, where `<VERSION>` 55is the version being released, e.g. `git tag -s v2.6.0`. 56 57Use the version name as the short message and the release notes as 58the body (long) message. 59 60#### Signing the headers 61 62This will create ASCII-armored signatures for the headers that are 63uploaded to the GitHub release: 64 65``` 66$ gpg2 --armor --output catch.hpp.asc --detach-sig catch.hpp 67$ gpg2 --armor --output catch_reporter_automake.hpp.asc --detach-sig catch_reporter_automake.hpp 68$ gpg2 --armor --output catch_reporter_teamcity.hpp.asc --detach-sig catch_reporter_teamcity.hpp 69$ gpg2 --armor --output catch_reporter_tap.hpp.asc --detach-sig catch_reporter_tap.hpp 70$ gpg2 --armor --output catch_reporter_sonarqube.hpp.asc --detach-sig catch_reporter_sonarqube.hpp 71``` 72 73_GPG does not support signing multiple files in single invocation._ 74