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