1= Releases 2 3== General notes 4 5* Avoid tagging commits in the `master` branch. 6* Release branches should have annotated tags and a CHANGELOG.md. 7* The steps below detail creation of a brand new 1.0.0 release. 8 Some steps would be omitted for minor releases. 9 10== Creating an initial release 11 12=== Update documentation 13 14Update references to version numbers in relevant documentation to the new 15version you intend to release. 16 17[source,console] 18---- 19git checkout master 20vim docs/installation.adoc 21git add docs/installation.adoc 22git commit 23git push 24---- 25 26=== Create branch 27 28Release branches have names of the form `release/N.x`, where N is the major 29version (and `x` is a literal -- not a placeholder). 30 31[source,console] 32---- 33git checkout -b release/1.x master 34---- 35 36[[update-changelog-and-version]] 37=== Update CHANGELOG and version 38 39[source,console] 40---- 41vim CHANGELOG.md 42# Add/update CHANGELOG entry for the new version 43git add CHANGELOG.md 44 45echo 1.0.0 > version.txt 46git add -f version.txt 47 48git commit 49---- 50 51=== Create tag 52 53An initial release would be tagged as follows: 54 55[source,console] 56---- 57git tag -a v1.0.0 -m '' 58---- 59 60=== Push branch and tag 61 62[source,console] 63---- 64# push the branch 65git push origin release/1.x 66 67# push the tag 68git push origin v1.0.0 69---- 70 71=== Edit tagged release description on GitHub 72 73. Navigate to the link:#https://github.com/rnpgp/rnp/releases[Releases] page; 74 75. Edit the tag that was just pushed; 76 77. Fill the tag's description with data from the corresponding `CHANGELOG` 78 entries of the same tag version; 79 80. Publish the release. 81 82 83== Creating a new release 84 85Maintaining a release branch involves cherry-picking hotfixes and 86similar commits from the `master` branch, while following the rules for 87Semantic Versioning. 88 89The steps below will show the release of version 1.0.1. 90 91=== Add desired changes 92 93Cherry-pick the appropriate commits into the appropriate `release/N.x` branch. 94 95To see what commits are in `master` that are not in the release branch, you 96can observe the lines starting with `+` in: 97 98[source,console] 99---- 100git cherry -v release/1.x master 101---- 102 103It is often useful to pick a range of commits. For example: 104 105[source,console] 106---- 107git checkout release/0.x 108git cherry-pick a57b36f^..e23352c 109---- 110 111If there are merge commits in this range, this will not work. 112Instead, try: 113 114[source,console] 115---- 116git checkout release/0.x 117git cherry release/0.x master | grep '^+ ' | cut -c 3-9 | \ 118 while read commit; do git cherry-pick $commit; done 119---- 120 121From here, you can follow the steps for an initial release, 122starting with <<update-changelog-and-version>>. 123