1 files changed, 81 insertions, 0 deletions
diff --git a/docs/chapters/releases.sgml b/docs/chapters/releases.sgml
new file mode 100644
index 00000000..07195a15
--- /dev/null
+++ b/docs/chapters/releases.sgml
@@ -0,0 +1,81 @@
+<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 (patholigical) 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>
+</chapter>