--- /dev/null
+=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>.
~ianmdlvl / dgit.git / commitdiff