From 43d55873eaa21613c7ca4ad5834e7e14600fcf1e Mon Sep 17 00:00:00 2001 From: Guido Günther Date: Mon, 13 Nov 2017 15:49:35 +0100 Subject: docs: better explain dch operation Closes: #880552 --- docs/chapters/releases.xml | 241 +++++++++++++++++++++++++++++---------------- docs/common.ent | 2 + docs/manpages/gbp-dch.xml | 100 +++++++++++-------- 3 files changed, 214 insertions(+), 129 deletions(-) diff --git a/docs/chapters/releases.xml b/docs/chapters/releases.xml index 692d72bf..1bf99ab1 100644 --- a/docs/chapters/releases.xml +++ b/docs/chapters/releases.xml @@ -1,33 +1,91 @@ - Releases and Snapshots - 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. - - The simplest way is doing all the changes to the - without touching - debian/changelog at all. Then, when done, do: - + Releases and Snapshots + + + 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. + + + + 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. + + + + Maintaining <filename>debian/changelog</filename> + + Creating &changelog; just before the release + + The simplest way is doing all the changes to the + without touching + debian/changelog at all. Then, when done, do: + &gbp-dch; - 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; - . + + 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. + + + + Incrementally filling &changelog; + + 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: + +&gbp-dch; + + You can then commit the debian/changelog + to have your current changes recorded. Later invocations of + &gbp-dch; will check when + debian/changelog was last modified and + not add these commits again. Upon your last call of &gbp-dch; + before releasing the package add + again to have the UNRELEASED distribution + in the changelog turned into unstable. + + + + + + Creating snapshots with increasing version numbers - But what if you want to have an (unreleased) snapshot for intermediate testing: + 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 UNRELEASED 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; is means that also all your test builds + have the same version number which makes them hard to + distinguish in e.g. continous integration pipelines. + + + + To address these shortcomings &gbp-dch; has a + 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: &gbp-dch; - will generate a snapshot release with a specially crafted version number - and a warning in the changelog that this is a snapshot release: - + + will generate a snapshot release with a specially crafted version number + and a warning in the changelog that this is a snapshot release: + git-buildpackage (0.3.7~1.gbp470ce2) UNRELEASED; urgency=low @@ -35,14 +93,16 @@ git-buildpackage (0.3.7~1.gbp470ce2) UNRELEASED; urgency=low * add support for automatic snapshot - During subsequent calls with , 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: + + During subsequent calls with , 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 comitting the changelog first): -&gbp-dch; +&gbp-dch; - will fetch the commit id and add changelog entries from that point to the + 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: @@ -52,41 +112,45 @@ git-buildpackage (0.3.7~1.gbp470ce2) UNRELEASED; urgency=low After testing, you can remove the snapshot header by a final &gbp-dch; call: -&gbp-dch; =HEAD +&gbp-dch; - 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 if you want to add further changelog - entries—or you can (of course) use again. + 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 . - - Customizing snapshot numbers - 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: + + Customizing snapshot numbers + 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: &gbp-dch; =1 &gbp-dch; ='snapshot + 2' &gbp-dch; ='os.popen("git-log --pretty=oneline | wc -l").readlines()[0]' &gbp-dch; =`git-log --pretty=oneline debian/0.3.3 | wc -l` - -You can also add the snapshot-number calculation to gbp.conf: - + + You can also add the snapshot-number calculation to gbp.conf: + [DEFAULT] snapshot-number = os.popen("git-log --pretty=oneline | wc -l").readlines()[0] - - - More on commit messages - You can use to include the full commit - message in the changelog; note that you will lose the formatting though, - since &dch; wraps lines by itself. - Additionally, there are tags and - available to customize the commit message. Each tag -has to start at the beginning of a single line. For example, the git commit message + + + + + Tuning commit messages + + You can use to include the full commit + message in the changelog. If you want to tweak the formatting + there's a . + + + Additionally, there are tags and + available to customize the commit message. Each tag + has to start at the beginning of a single line. For example, the git commit message New upstream version @@ -98,58 +162,63 @@ Thanks: cool upstream * New upstream version (Closes: #1000) - thanks to cool upstream You can use the tag multiple times. - - -There are several tags to further customize what (and how) commit messages get -included into the changelog: - -To exclude a commit from the generated changelog, use: - + + + There are several tags to further customize what (and how) commit messages get + included into the changelog: + + + To exclude a commit from the generated changelog, use: + + Gbp-Dch: Ignore -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 + 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 Set correct branchnames in debian/gbp.conf Gbp-Dch: Ignore -will not show up in the generated changelog in any way. - - -To include the full commit message in the changelog, use: + will not show up in the generated changelog in any way. + + + To include the full commit message in the changelog, use: Gbp-Dch: Full - - -To only include the short description in the changelog and skip the body, use: + + + To only include the short description in the changelog and skip the body, use: Gbp-Dch: Short -The latter only takes effect when running &gbp-dch; with the - option since including only the short -description is the default. - - -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 and -fields in debian/control. See -Cl2vcs for how this looks. - - -The inclusion of the commit id can be done automatically -via &gbp-dch;'s option. Using -=7 would change the above example to: + The latter only takes effect when running &gbp-dch; with the + option since including only the short + description is the default. + + + 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 and + fields in + debian/control. See Cl2vcs for how + this looks. + + + The inclusion of the commit id can be done automatically + via &gbp-dch;'s option. Using + =7 would change the above example to: - * [571bfd4] New upstream version (Closes: #1000) - thanks to cool upstream + * [571bfd4] New upstream version (Closes: #1000) - thanks to cool upstream -This makes it much easier to see which commit actually fixed bug #1000. - + This makes it much easier to see which commit actually fixed bug #1000. + diff --git a/docs/common.ent b/docs/common.ent index c2109551..7f180064 100644 --- a/docs/common.ent +++ b/docs/common.ent @@ -71,6 +71,8 @@ pristine-tar"> svn-buildpackage"> + debian/changelog"> + DEP-14"> here"> Python format string"> diff --git a/docs/manpages/gbp-dch.xml b/docs/manpages/gbp-dch.xml index abdb0093..65f491ab 100644 --- a/docs/manpages/gbp-dch.xml +++ b/docs/manpages/gbp-dch.xml @@ -25,6 +25,10 @@ branch_name tag-format + + commitish + commitish + @@ -35,16 +39,6 @@ - - - - - - - commitish - commitish - - version version @@ -87,21 +81,33 @@ DESCRIPTION - &gbp-dch; reads git commit messages and generates the &debian; - changelog from it. If no arguments are given, &gbp-dch; starts - from the commit corresponding to the last tagged Debian package - version up to the current tip of the current branch. If the - distribution of the topmost section in - debian/changelog - is UNRELEASED, the changelog entries will be - inserted into this section. Otherwise, a new section will be - created. + &gbp-dch; reads git commit messages and generates the &debian; + changelog from it. It starts at a given commit specified by the + option up to the current + HEAD. For each commit found it adds the + commit message to the changelog. If is + not given the commit to start from is determined by the + following rules (first one matches): + + + + The start commit is read from the snapshot banner (see below for + details) + If the topmost version of the + debian/changelog is alread tagged. Use the commit + the tag points to as start commit. + The last commit that modified debian/changelog is + used as start commit. + + + This is called automatic mode. - If is given &gbp-dch;, tries to guess the - last &git; commit documented in the changelog - this only works in snapshot - mode. Otherwise, can be used to tell &gbp-dch; - at which point it should start in the &git; history. + If the distribution of the topmost section in + debian/changelog is + UNRELEASED, the changelog entries will be + inserted into this section. Otherwise a new section will be + created. If one ore more paths are given as arguments &gbp-dch; will only @@ -120,16 +126,16 @@ The above relies on the option - pointing to the current branch - and pointing to the - corresponding upstream branch in order to find the right merge - points of these branches. Furthermore &gbp-dch; must be able to - identify git tags from upstream and Debian version numbers. If - you're not using the defaults check - the - and options and make sure they match + pointing to the current branch and + pointing to the corresponding + upstream branch in order to find the right merge points of these + branches. Furthermore &gbp-dch; must be able to identify git + tags from upstream and Debian version numbers. If you're not + using the defaults check the and + options and make sure they match the tags created by e.g. &gbp-import-orig; (when using tarballs) - or upstream's tagging pattern (when using upstream's git directly). + or upstream's tagging pattern (when using upstream's git + directly). @@ -203,9 +209,8 @@ - Guess the last commit documented in the changelog from the - snapshot banner (or from the last tag if no snapshot banner exists). - This option can't be set via &gbp.conf;. + This option is ignored for compatiblity with older + versions. It used to trigger automatic mode. @@ -268,11 +273,18 @@ - 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 auto incremented with every new snapshot - release to avoid packages downgrades during snapshot testing. + Create a snapshot release entry. It uses a snapshot + release number which is smaller than the final release + number and adds a warning banner to the changelog + entry. The version number is being auto incremented with + every new snapshot release. + + The snapshot banner is also used by &gbp-dch; to determine which + entries are already in the changelog. This prevents duplicated + entries in debian/changelog when you did + not commit the changelog yet. + @@ -289,10 +301,12 @@ - Remove any snapshot release banners and version suffixes, set - the current distribution to unstable, and - open the changelog for final tweaking. - This option can't be set via &gbp.conf;. + Remove any snapshot release banners and version suffixes + (if any), set the current distribution to + unstable, and open the + changelog for final tweaking. This option can't be set + via &gbp.conf;. It's usually used to finalize the + changelog before making a release. -- cgit v1.2.3