aboutsummaryrefslogtreecommitdiff
path: root/docs/chapters/releases.sgml
blob: 4e1874b4517b659456c71694063b95c0dc545388 (plain)
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
<chapter id="gbp.releases">
    <title>Releases and Snapshots</title>
    <para>When branching and merging frequently, the different Debian changelog
    entries on the different branches tend to get into the way of the automatic
    merge and the the merge fails - leaving the (pathological) merge to the
    committer. In order to avoid this &git-dch; offers a way for creating
    changelog entries from &git; commits before doing a
    release or anytime between releases.</para> 
    <para>
    The simplest way is doing all the changes to the
    <option>debian-branch</option> without touching
    <emphasis>debian/changelog</emphasis> at all. Then, when done, do:
    </para>
<screen>
&git-dch; <option>--release</option>
</screen>
    <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 file editing by invoking &dch;
    <option>--release</option>.</para>
    <para>
    But what if you want to have an (unreleased) snapshot for intermediate testing:
<screen>
&git-dch; <option>--snapshot</option>
</screen>
   <para>will generate a snapshot release with a specially crafted version number
   and a warning in the changelog that this is a snapshort 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 banners contains the
   commit id of the current branch head, &git-dch; can figure out what to
   append to the changelog by itself:
<screen>
&git-dch; <option>--snapshot</option> <option>--auto</option>
</screen>
   will fetch the commit id 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>
<screen>
&git-dch; <option>--since</option>=<replaceable>e76a6a180a57701ae4ae381f74523cacb3152780</replaceable> <option>--snapshot</option>
</screen>
   <para>
   After testing you can remove the snapshot header by a final &git-dch; call:
   </para>
<screen>
&git-dch; <option>--since</option>=<replaceable>HEAD</replaceable> <option>--release</option>
</screen>
   <para>
   This will add no further entries but simply remove the specially crafted
   version number and the snapshort header. Again you can use any commit id
   or tag instead of <option>HEAD</option> if you want to add further changelog
   entries - or you can (of course) use <option>--auto</option> again.
   </para>
<sect1 id="gbp.release.numbers">
    <title>Customizing snapshot numbers</title>
    <para>If the auto incrementing of the snapshot number doesn't suite you needs you
    can give any python expression that evaluates to a positive integer to
    calculate the new snapshot number:</para>
<screen>
&git-dch; <option>-S</option> <option>-a</option> <option>--snapshot-number</option>=<replaceable>1</replaceable>
&git-dch; <option>-S</option> <option>-a</option> <option>--snapshot-number</option>=<replaceable>'snapshot + 2'</replaceable>
&git-dch; <option>-S</option> <option>-a</option> <option>--snapshot-number</option>=<replaceable>'os.popen("git-log --pretty=oneline | wc -l").readlines()[0]'</replaceable>
&git-dch; <option>-S</option> <option>-a</option> <option>--snapshot-number</option>=<replaceable>`git-log --pretty=oneline debian/0.3.3 | wc -l`</replaceable>
</screen>
<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>
</sect1>
<sect1 id="gbp.release.commit">
    <title>More on commit messages</title>
    <para>You can use <option>--full</option> to include the full commit
    message in the changelog, note that you will lose the formatting though,
    since &dch; wraps lines by itself.</para>
    <para>Additionally you can use tags to customize the commit message, 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 multiple <option>Closes:</option> tags.
</para>
</sect1>
</chapter>