chiark / gitweb /
dgit-maint-bpo(7): new manpage
authorSean Whitton <spwhitton@spwhitton.name>
Sun, 3 Mar 2019 00:53:39 +0000 (17:53 -0700)
committerIan Jackson <ijackson@chiark.greenend.org.uk>
Sat, 20 Jul 2019 18:36:41 +0000 (19:36 +0100)
Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
Closes: #857490

Makefile
dgit-maint-bpo.7.pod [new file with mode: 0644]
po4a/po4a.cfg

index 4ba6d12..3a4f9e0 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -43,7 +43,8 @@ MAN7PAGES=dgit.7                              \
        dgit-maint-merge.7 dgit-maint-gbp.7     \
        dgit-maint-debrebase.7                  \
        dgit-downstream-dsc.7                   \
-       dgit-sponsorship.7
+       dgit-sponsorship.7                      \
+       dgit-maint-bpo.7
 
 TXTDOCS=README.dsc-import
 PERLMODULES= \
diff --git a/dgit-maint-bpo.7.pod b/dgit-maint-bpo.7.pod
new file mode 100644 (file)
index 0000000..e977d25
--- /dev/null
@@ -0,0 +1,141 @@
+=head1 NAME
+
+dgit - tips for maintaining official Debian backports
+
+=head1 INTRODUCTION
+
+This document describes elements of a workflow for using B<dgit> to
+maintain an official Debian backport.  We do not assume that whoever
+uploads the package to Debian unstable is using B<dgit>.
+
+=head1 TERMINOLOGY
+
+Let the I<master> branch contain the packaging history uploaded to
+Debian unstable, and the I<buster-bpo> branch be where you prepare
+your uploads to the B<buster-backports> suite.
+
+A B<merging> backports workflow means that each time an upload
+migrates to Debian testing and you want to prepare an upload to
+B<buster-backports>, you do something like this:
+
+=over 4
+
+    % git checkout buster-bpo
+    % git merge master
+    % dch --bpo
+    % # any other changes needed for backporting
+    % git commit -a
+    % # try a build
+
+=back
+
+A B<rebasing> backports workflow means that you throw away the history
+of the I<buster-bpo> branch each time a new version migrates to Debian
+testing, something equivalent to this:
+
+=over 4
+
+    % git checkout -B buster-bpo master
+    % dch --bpo
+    % # any other changes needed for backporting
+    % git commit -a
+    % # try a build
+
+=back
+
+If you use a merging backports workflow, your changelog contains
+entries for each previous upload to B<buster-backports>; in a rebasing
+workflow, it contains only the latest.
+
+=head1 CHOOSING BETWEEN THE TWO WORKFLOWS
+
+If backporting involves making no (additional) changes to the upstream
+source, whether you use a merging or rebasing backports workflow is a
+matter of personal preference.  There are good arguments in favour of
+both workflows fitting the semantics of the B<*-backports> suites.
+
+If you have to make changes to the upstream source to make the package
+work on machines running Debian stable, it is advisable to choose a
+rebasing workflow.  This ensures that dgit can automatically update
+the debian/patches directory without any manual intervention.
+
+=head1 TIPS FOR A MERGING WORKFLOW
+
+=head2 Use dgit's branches
+
+If you do not yourself upload the package to Debian unstable, it is
+usually easiest to use dgit's branches, and ignore the configured
+Vcs-Git repository.
+
+You would use
+
+=over 4
+
+    % dgit clone foo bullseye
+
+=back
+
+for a new backport of package 'foo' to B<buster-backports>, and then
+
+=over 4
+
+    % dgit fetch bullseye
+    % git merge dgit/dgit/bullseye
+
+=back
+
+when new versions migrate to Debian testing.
+
+=head1 TIPS FOR A REBASING WORKFLOW
+
+=head2 Use dgit's branches
+
+If you do not yourself upload the package to Debian unstable, it is
+usually easiest to use dgit's branches, and ignore the configured
+Vcs-Git repository.  For each new version from Debian testing, you
+would
+
+=over 4
+
+    % dgit fetch bullseye
+    % git checkout -B buster-bpo dgit/dgit/bullseye
+    % # use git-cherry-pick(1) to (re)apply any needed backporting fixes
+
+=back
+
+=head2 Overwriting
+
+B<dgit push> tries hard to prevent you from accidentally overwriting
+uploads that it thinks aren't represented in the git history you are
+trying to upload.  This is mainly to prevent accidentally overwriting
+NMUs.
+
+With a rebasing backports workflow, dgit will think that every upload
+of a new version from Debian testing might be accidentally overwriting
+uploads.  You will need to explicitly indicate the upload to
+B<buster-backports> you wish to overwrite.
+
+Suppose that the last upload to B<buster-backports> was versioned
+I<1.2.2-1~bpo10+1> and you have now prepared I<1.2.3-1~bpo10+1> for
+upload.  When you B<dgit push>, you will need to pass
+I<--overwrite=1.2.2-1~bpo10+1>.
+
+Alternatively, you can perform the pseudomerge that I<--overwrite>
+would have done yourself:
+
+=over 4
+
+    % dgit fetch buster-backports
+    % git merge -s ours dgit/dgit/buster-backports
+    % dgit push-source
+
+=back
+
+=head1 SEE ALSO
+
+dgit(1), dgit(7), https://backports.debian.org/
+
+=head1 AUTHOR
+
+This manpage was written and is maintained by Sean Whitton
+<spwhitton@spwhitton.name>.
index 47e8b13..491c3d0 100644 (file)
@@ -14,6 +14,7 @@
 [type: pod] ../dgit-maint-debrebase.7.pod $lang:translated/man/$lang/man7/dgit-maint-debrebase.7.pod master:file=dgit-maint-debrebase_7
 [type: pod] ../dgit-downstream-dsc.7.pod $lang:translated/man/$lang/man7/dgit-downstream-dsc.7.pod master:file=dgit-downstream-dsc_7
 [type: pod] ../dgit-sponsorship.7.pod $lang:translated/man/$lang/man7/dgit-sponsorship.7.pod master:file=dgit-sponsorship_7
+[type: pod] ../dgit-maint-bpo.7.pod $lang:translated/man/$lang/man7/dgit-maint-bpo.7.pod master:file=dgit-maint-bpo_7
 [type: pod] ../git-debrebase.1.pod $lang:translated/man/$lang/man1/git-debrebase.1.pod master:file=git-debrebase_1
 [type: pod] ../git-debrebase.5.pod $lang:translated/man/$lang/man5/git-debrebase.5.pod master:file=git-debrebase_5
 [type: pod] ../git-debpush.1.pod $lang:translated/man/$lang/man1/git-debpush.1.pod master:file=git-debpush_1