From fac9439ebebc415261f81eeed1b65d8bdcd876e8 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sat, 2 Mar 2019 17:53:39 -0700 Subject: dgit-maint-bpo(7): new manpage Signed-off-by: Sean Whitton Closes: #857490 --- dgit-maint-bpo.7.pod | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 dgit-maint-bpo.7.pod (limited to 'dgit-maint-bpo.7.pod') 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 to +maintain an official Debian backport. We do not assume that whoever +uploads the package to Debian unstable is using B. + +=head1 TERMINOLOGY + +Let the I branch contain the packaging history uploaded to +Debian unstable, and the I branch be where you prepare +your uploads to the B suite. + +A B backports workflow means that each time an upload +migrates to Debian testing and you want to prepare an upload to +B, 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 backports workflow means that you throw away the history +of the I 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; 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, 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 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 you wish to overwrite. + +Suppose that the last upload to B 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, 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 +. -- cgit v1.2.3