diff options
| -rw-r--r-- | Makefile | 3 | ||||
| -rw-r--r-- | dgit-maint-bpo.7.pod | 141 | ||||
| -rw-r--r-- | po4a/po4a.cfg | 1 |
3 files changed, 144 insertions, 1 deletions
@@ -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 index 0000000..e977d25 --- /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>. diff --git a/po4a/po4a.cfg b/po4a/po4a.cfg index 47e8b13..491c3d0 100644 --- a/po4a/po4a.cfg +++ b/po4a/po4a.cfg @@ -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 |