1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
<chapter id="gbp.releases">
<title>Releases and Snapshots</title>
<para>
The &changelog; gives the &debian; package a version number
and keeps track of changes made to the package in a particular
version. While the changelog can still be maintained by hand we
can make use of &gbp-dch; to have our &git; commit messages end up
in &changelog;. This avoids the double maintenance of the &git;
commit history and the &debian; changelog. If you don't want a
one to one mapping of changelog entries to &git; commits you're
free to edit the changelog by hand at any point.
</para>
<para>
Not committing changelog entries with the actual modifications
also has the advantage that the changelog won't cause any trouble
when cherry-picking patches from different branches. It can be
created when releasing the package or after performing several
commits. Invocations of &dch; and &gbp-dch; can be mixed.
</para>
<sect1>
<title>Maintaining <filename>debian/changelog</filename></title>
<sect2>
<title>Creating &changelog; just before the release</title>
<para>
The simplest way is doing all the changes to the
<option>debian-branch</option> without touching
<filename>debian/changelog</filename> at all. Then, when done, do:
</para>
<programlisting>
&gbp-dch; <option>--release</option>
</programlisting>
<para>
This will look up the latest released version in the changelog,
increment the version in the &debian; changelog, generate changelog
messages from the corresponding &git; commit id up to the branch head, and
finally spawns an editor for final changelog editing.
</para>
</sect2>
<sect2>
<title>Incrementally filling &changelog;</title>
<para>
You can run &gbp-dch; without any options to make it add all
commit messages since the last &debian; tag to a new UNRELEASED
changelog section:
<programlisting>
&gbp-dch;
</programlisting>
You can then commit the <filename>debian/changelog</filename>
to have your current changes recorded. Later invocations of
&gbp-dch; will check when
<filename>debian/changelog</filename> was last modified and
not add these commits again. Upon your last call of &gbp-dch;
before releasing the package add <option>--release</option>
again to have the <emphasis>UNRELEASED</emphasis> distribution
in the changelog turned into <emphasis>unstable</emphasis>.
</para>
</sect2>
</sect1>
<sect1>
<title>Creating snapshots with increasing version numbers</title>
<para>
The downside of the above methods is that you either have the
version number of the last release in &changelog; or that you
have a changelog entry with <emphasis>UNRELEASED</emphasis> that
has the same version number for all commits you do during the
development cycle of your package. Although this is common
practice in &debian; it means that also all your test builds
have the same version number which makes them hard to
distinguish in e.g. continuous integration pipelines.
</para>
<para>
To address these shortcomings &gbp-dch; has a
<option>--snapshot</option> option that can be used to create
(unreleased) snapshots for intermediate testing with a version
number that is lower than the one of the final package:
</para>
<programlisting>
&gbp-dch; <option>--snapshot</option>
</programlisting>
<para>
will generate a snapshot release with a specially crafted version number
and a warning in the changelog that this is a snapshot release:
</para>
<programlisting>
git-buildpackage (0.3.7~1.gbp470ce2) UNRELEASED; urgency=low
** SNAPSHOT build @470ce29ec7877705c844474a2fd89869aea0406d **
* add support for automatic snapshot
</programlisting>
<para>
During subsequent calls with <option>--snapshot</option>, this
version number will continue to increase. Since the snapshot
banner contains the commit id of the current branch HEAD,
&gbp-dch; can figure out what to append to the changelog by itself
(even without committing the changelog first):
<programlisting>
&gbp-dch; <option>--snapshot</option>
</programlisting>
will fetch the commit id from &changelog; and add changelog entries from that point to the
current HEAD—again auto incrementing the version number. If you don't want
to start at that commit id, you can specify any id or tag with:</para>
<programlisting>
&gbp-dch; <option>--since</option>=<replaceable>e76a6a180a57701ae4ae381f74523cacb3152780</replaceable> <option>--snapshot</option>
</programlisting>
<para>
After testing, you can remove the snapshot header by a final &gbp-dch; call:
</para>
<programlisting>
&gbp-dch; <option>--release</option>
</programlisting>
<para>
This will pick new commit if present and remove the specially
crafted version number and the snapshot header. If you want finer
control of what is being added you can again use the <option>--since</option>.
</para>
<sect2 id="gbp.release.numbers">
<title>Customizing snapshot numbers</title>
<para>If the auto incrementing of the snapshot number doesn't suite your needs, you
can give any Python expression that evaluates to a positive integer to
calculate the new snapshot number:</para>
<programlisting>
&gbp-dch; <option>-S</option> <option>-a</option> <option>--snapshot-number</option>=<replaceable>1</replaceable>
&gbp-dch; <option>-S</option> <option>-a</option> <option>--snapshot-number</option>=<replaceable>'snapshot + 2'</replaceable>
&gbp-dch; <option>-S</option> <option>-a</option> <option>--snapshot-number</option>=<replaceable>'os.popen("git-log --pretty=oneline | wc -l").readlines()[0]'</replaceable>
&gbp-dch; <option>-S</option> <option>-a</option> <option>--snapshot-number</option>=<replaceable>`git-log --pretty=oneline debian/0.3.3 | wc -l`</replaceable>
</programlisting>
<para>
You can also add the snapshot-number calculation to <filename>gbp.conf</filename>:
</para>
<programlisting>
[DEFAULT]
snapshot-number = os.popen("git-log --pretty=oneline | wc -l").readlines()[0]
</programlisting>
</sect2>
</sect1>
<sect1 id="gbp.release.commit">
<title>Tuning commit messages</title>
<para>
You can use <option>--full</option> to include the full commit
message in the changelog. If you want to tweak the formatting
there's a <option>--customizations</option>.
</para>
<para>
Additionally, there are tags <option>Closes:</option> and
<option>Thanks:</option> available to customize the commit message. Each tag
has to start at the beginning of a single line. For example, the git commit message
<screen>
New upstream version
Closes: #1000
Thanks: cool upstream
</screen>
would result in a changelog entry:
<screen>
* New upstream version (Closes: #1000) - thanks to cool upstream
</screen>
You can use the <option>Closes:</option> tag multiple times.
</para>
<para>
There are several tags to further customize what (and how) commit messages get
included into the changelog:
</para>
<para>
To exclude a commit from the generated changelog, use:
</para>
<para>
<screen>
Gbp-Dch: Ignore
</screen>
This is e.g. useful if you're just fixing up a previous commit and couldn't
amend it, or for other janitorial commits that really don't need to end up in
the changelog. For example, the following git commit message
<screen>
Set correct branchnames in debian/gbp.conf
Gbp-Dch: Ignore
</screen>
will not show up in the generated changelog in any way.
</para>
<para>
To include the full commit message in the changelog, use:
<screen>
Gbp-Dch: Full
</screen>
</para>
<para>
To only include the short description in the changelog and skip the body, use:
<screen>
Gbp-Dch: Short
</screen>
The latter only takes effect when running &gbp-dch; with the
<option>--full</option> option since including only the short
description is the default.
</para>
<para>
Usually, changelog entries should correspond to a single &git;
commit. In this case, it's convenient to include the commit id
in the changelog entry. This has the advantage that it's easy
for people to identify changes without having to write very
extensive changelog messages—the link back to &git; can be
automated via the <option>Vcs-Browser</option> and
<option>Vcs-Git</option> fields in
<filename>debian/control</filename>. See <ulink
url="https://honk.sigxcpu.org/cl2vcs"> Cl2vcs</ulink> for how
this looks.
</para>
<para>
The inclusion of the commit id can be done automatically
via &gbp-dch;'s <option>--id-length</option> option. Using
<option>--id-length</option>=<replaceable>7</replaceable> would change the above example to:
<screen>
* [571bfd4] New upstream version (Closes: #1000) - thanks to cool upstream
</screen>
This makes it much easier to see which commit actually fixed bug #1000.
</para>
</sect1>
</chapter>
|
