From 7136216ac6ad77eabcfe35e802ea498102150046 Mon Sep 17 00:00:00 2001
From: Sean Whitton <spwhitton@spwhitton.name>
Date: Sat, 2 Mar 2019 17:53:39 -0700
Subject: [PATCH] dgit-maint-bpo(7): new manpage

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
---
 Makefile             |   3 +-
 dgit-maint-bpo.7.pod | 141 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 143 insertions(+), 1 deletion(-)
 create mode 100644 dgit-maint-bpo.7.pod

diff --git a/Makefile b/Makefile
index 380bdb03..c4105640 100644
--- a/Makefile
+++ b/Makefile
@@ -42,7 +42,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
index 00000000..e977d258
--- /dev/null
+++ b/dgit-maint-bpo.7.pod
@@ -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>.
-- 
2.20.1

