add some basic documentation for git-dch

10 files changed, 126 insertions, 11 deletions

diff --git a/docs/chapters/chapters.ent b/docs/chapters/chapters.ent
index 68fea426..fd7c6da3 100644
--- a/docs/chapters/chapters.ent
+++ b/docs/chapters/chapters.ent
@@ -2,5 +2,6 @@
 <!ENTITY ch.workflow SYSTEM "workflow.sgml">
 <!ENTITY ch.import SYSTEM "import.sgml">
 <!ENTITY ch.building SYSTEM "building.sgml">
+<!ENTITY ch.releases SYSTEM "releases.sgml">
 <!ENTITY ch.cfgfile SYSTEM "cfgfile.sgml">
 <!ENTITY ch.special SYSTEM "special.sgml">
diff --git a/docs/chapters/intro.sgml b/docs/chapters/intro.sgml
index 4097793d..683811e9 100644
--- a/docs/chapters/intro.sgml
+++ b/docs/chapters/intro.sgml
@@ -35,6 +35,9 @@
 	always build the package with &git-buildpackage;. In case you have
 	uncommitted changes in your source tree you can use the
 	<option>--git-ignore-new</option> option.</para></listitem>
+	<listitem><para>Optionally you can create the Debian changelog entries
+	using &git-dch; and create snapshot releases for testing using the
+	<option>--snapshot</option> option.</para></listitem>
 	<listitem><para>Once satisfied you can build the final package with
 	&git-buildpackage; <option>--git-tag</option>. This
 	additionally creates a tag within &git; so you can switch back to that
diff --git a/docs/chapters/releases.sgml b/docs/chapters/releases.sgml
new file mode 100644
index 00000000..58ac40f9
--- /dev/null
+++ b/docs/chapters/releases.sgml
@@ -0,0 +1,62 @@
+<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
+    <emphasis>debian</emphasis>-branch without touching
+    <emphasis>debian/changelog</emphasis> at all. Then, when done, do:
+    </para>
+<screen>
+&git-dch; --release
+</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; --snapshot
+</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; --snapshot --auto
+</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; --since=e76a6a180a57701ae4ae381f74523cacb3152780 --snapshot
+</screen>
+   <para>
+   After testing you can remove the snapshot header by a final &git-dch; call:
+   </para>
+<screen>
+&git-dch; --since=HEAD --release
+</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>
+</chapter>
diff --git a/docs/chapters/special.sgml b/docs/chapters/special.sgml
index 3ac7a80f..e63da062 100644
--- a/docs/chapters/special.sgml
+++ b/docs/chapters/special.sgml
@@ -1,4 +1,4 @@
-<chapter id="gbp.special">
+    <chapter id="gbp.special">
     <title>Special usage cases</title>
     <sect1 id="gbp.special.dfsgfree">
     <title>Handling non-DFSG clean upstream sources</title>
diff --git a/docs/common.ent b/docs/common.ent
index 31e9835a..c2f26502 100644
--- a/docs/common.ent
+++ b/docs/common.ent
@@ -16,6 +16,7 @@
 
   <!ENTITY debian      "<productname>Debian</productname>">
   <!ENTITY git	       "<productname>Git</productname>">
+  <!ENTITY dch	       "<productname>dch</productname>">
   <!ENTITY pbuilder    "<productname>Pbuilder</productname>">
   <!ENTITY gitloaddirs "<productname>Git_load_dirs</productname>">
   <!ENTITY debuild     "<productname>Debuild</productname>">
diff --git a/docs/manpages/git-buildpackage.sgml b/docs/manpages/git-buildpackage.sgml
index 00c9b856..e1803ca8 100644
--- a/docs/manpages/git-buildpackage.sgml
+++ b/docs/manpages/git-buildpackage.sgml
@@ -163,7 +163,7 @@
   <refsect1>
     <title>SEE ALSO</title>
 
-    <para>git-import-dsc (1), git-import-orig (1), debuild (1), git (1)</para>
+    <para>git-import-dsc (1), git-import-orig (1), debuild (1), git (1), git-dch (1)</para>
 
   </refsect1>
   <refsect1>
diff --git a/docs/manpages/git-dch.sgml b/docs/manpages/git-dch.sgml
index ed0d99e1..9b058bb7 100644
--- a/docs/manpages/git-dch.sgml
+++ b/docs/manpages/git-dch.sgml
@@ -15,7 +15,7 @@
   <refnamediv>
     <refname>&git-dch;</refname>
 
-    <refpurpose>Generate Debian changelog from git commit messages</refpurpose>
+    <refpurpose>Generate the Debian changelog from git commit messages</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <cmdsynopsis>
@@ -25,19 +25,36 @@
       <arg><option>--debian-branch=</option><replaceable>branch_name</replaceable></arg>
       <arg><option>--debian-tag=</option><replaceable>tag-format</replaceable></arg>
       <arg><option>--since=</option><replaceable>commitish</replaceable></arg>
+      <arg><option>--snapshot</option></arg>
+      <arg><option>--release</option></arg>
+      <arg><option>--auto</option></arg>
+      <arg><option>--git-log=</option><replaceable>git-log-options</replaceable></arg>
+      <arg choice="plain"><replaceable>[path1 path2]</replaceable></arg>
     </cmdsynopsis>
   </refsynopsisdiv>
   <refsect1>
     <title>DESCRIPTION</title>
     <para>
-    &git-dch; reads git commit messages and generates the debian changelog from it. If no arguments
-    are given &git-dch; starts from the last tagged debian package version up
-    to the current tip of the <replaceable>debian-branch</replaceable>. If the
+    &git-dch; reads git commit messages and generates the debian changelog from
+    it. If no arguments are given &git-dch; starts from the last tagged debian
+    package version up to the current tip of the current branch. If the
     distribution of the topmost section in
     <filename>debian/changelog</filename> is <emphasis>UNRELEASED</emphasis>
     the changelog entries will be inserted into this section. Otherwise a new
-    section is being created.
-    </para>
+    section will be created.</para>
+    <para>If <option>--auto</option> is given &git-dch; tries to guess the
+    last &git; commit documented in the changelog - this only works in snapshot
+    mode. Otherwise <option>--since</option> can be used to tell &git-dch;
+    at which point it should start in the &git; history.</para>
+    <para>
+    The additional path arguments can be used to restrict the repository paths
+    &git-dch; looks at. Setting <replaceable>path</replaceable> to
+    <emphasis>debian/</emphasis> is a good choice if upstream uses &git; and
+    all Debian packaging changes are restricted to the
+    <replaceable>debian/</replaceable> subdir. In more sophisticated cases
+    (like backports) you can use <option>--git-log</option> to restrict the
+    generated changelog entries further. E.g. by using 
+    <option>--git-log=</option><replaceable>"--author=Foo Bar"</replaceable>.</para>
   </refsect1>
   <refsect1>
     <title>OPTIONS</title>
@@ -72,6 +89,36 @@
           <para>start reading commit messages at <replaceable>committish</replaceable></para>
         </listitem>
       </varlistentry>
+      <varlistentry>
+        <term><option>--auto</option></term>
+        <listitem>
+	  <para>Guess the last commit documented in the changelog from the
+	  snapshot banner (or from the last tag if no snapshot banner exists).
+	  </para>
+        </listitem>
+      <varlistentry>
+        <term><option>--snapshot</option></term>
+        <listitem>
+	  <para>create a snapshot release entry. This adds a snapshot release
+	  number and a warning banner to the changelog entry. The release
+	  version number is being autoincremented with every new snapshot
+	  release to avoid packages downgrades during snapshot testing.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>--release</option></term>
+        <listitem>
+	  <para>Remove any snapshot release banners and version suffixes, set
+	  the current distribution to <replaceable>unstable</replaceable> and
+	  open the changelog for final tweaking.</para>
+        </listitem>
+      <varlistentry>
+        <term><option>--git-log=</option><replaceable>git-log-options</replaceable>
+        </term>
+        <listitem>
+          <para>options passed on verbatim to git-log(1)</para>
+        </listitem>
+      </varlistentry>
     </variablelist>
   </refsect1>
   <refsect1>
@@ -80,7 +127,7 @@
   <refsect1>
     <title>SEE ALSO</title>
 
-    <para>git-buildpackage (1), git-import-dsc (1), git (1), git_load_dirs (1)</para>
+    <para>git-buildpackage (1), git-import-dsc (1), git-import-orig (1), git (1), git_load_dirs (1)</para>
 
   </refsect1>
   <refsect1>
diff --git a/docs/manpages/git-import-dsc.sgml b/docs/manpages/git-import-dsc.sgml
index 5f4e5d45..38940f76 100644
--- a/docs/manpages/git-import-dsc.sgml
+++ b/docs/manpages/git-import-dsc.sgml
@@ -111,7 +111,7 @@
   <refsect1>
     <title>SEE ALSO</title>
 
-    <para>git-buildpackage (1), git-import-orig (1), git (1), git_load_dirs (1)</para>
+    <para>git-buildpackage (1), git-import-orig (1), git (1), git_load_dirs (1), git-dch (1)</para>
   </refsect1>
   <refsect1>
     <title>AUTHOR</title>
diff --git a/docs/manpages/git-import-orig.sgml b/docs/manpages/git-import-orig.sgml
index 8553561c..a8900ddb 100644
--- a/docs/manpages/git-import-orig.sgml
+++ b/docs/manpages/git-import-orig.sgml
@@ -129,7 +129,7 @@
   <refsect1>
     <title>SEE ALSO</title>
 
-    <para>git-buildpackage (1), git-import-dsc (1), git (1), git_load_dirs (1)</para>
+    <para>git-buildpackage (1), git-import-dsc (1), git (1), git_load_dirs (1), git-dch (1)</para>
 
   </refsect1>
   <refsect1>
diff --git a/docs/manual.sgml b/docs/manual.sgml
index 246e6070..6d188fdc 100644
--- a/docs/manual.sgml
+++ b/docs/manual.sgml
@@ -20,6 +20,7 @@
   &ch.intro;
   &ch.import;
   &ch.building;
+  &ch.releases;
   &ch.cfgfile;
   &ch.special;