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### Approval testing
12
13Catch's releases are primarily validated against output from previous release, stored in `projects/SelfTest/Baselines`. To validate current sources, build the SelfTest binary and pass it to the `approvalTests.py` script: `approvalTests.py <path/to/SelfTest>`.
14
15There should be no differences, as Approval tests should be updated when changes to Catch are made, but if there are, then they need to be manually reviewed and either approved (using `approve.py`) or Catch requires other fixes.
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 placed in `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 commited 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,
46TAP, TeamCity) should also be attached as binaries, as they are dependent
47on a specific version of the single-include header.
48
49
50## Optional steps
51
52The following steps are optional, and do not have to be performed when releasing new version of Catch. However, they *should* happen, but they can happen the next day without losing anything significant.
53
54
55### vcpkg update
56
57Catch is maintaining its own port in Microsoft's package manager [vcpkg](https://github.com/Microsoft/vcpkg). This means that when new version of Catch is released, it should be posted there as well. `updateVcpkgPackage.py` can do a lot of necessary work for you, it creates a branch and commits necessary changes. You should review these changes, push and open a PR against vcpkg's upstream.
58
59Note that the script assumes you have your fork of vcpkg checked out in a directory next to the directory where you have checked out Catch, like so:
60```
61GitHub
62    Catch
63    vcpkg
64```
65
66