diff options
Diffstat (limited to 'docs/chapters/releases.xml')
| -rw-r--r-- | docs/chapters/releases.xml | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/docs/chapters/releases.xml b/docs/chapters/releases.xml new file mode 100644 index 00000000..692d72bf --- /dev/null +++ b/docs/chapters/releases.xml @@ -0,0 +1,155 @@ +<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, &gbp-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 + <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 file editing by invoking &dch; + <option>--release</option>.</para> + <para> + But what if you want to have an (unreleased) snapshot for intermediate testing: + </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 banners contains the + commit id of the current branch head, &gbp-dch; can figure out what to + append to the changelog by itself: +<programlisting> +&gbp-dch; <option>--snapshot</option> <option>--auto</option> +</programlisting> + 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> +<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>--since</option>=<replaceable>HEAD</replaceable> <option>--release</option> +</programlisting> + <para> + This will add no further entries but simply remove the specially crafted + version number and the snapshot 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 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> +</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, 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> |