diff options
author | Sean Whitton <spwhitton@spwhitton.name> | 2019-03-02 17:53:39 -0700 |
---|---|---|
committer | Ian Jackson <ijackson@chiark.greenend.org.uk> | 2019-07-20 19:36:41 +0100 |
commit | fac9439ebebc415261f81eeed1b65d8bdcd876e8 (patch) | |
tree | 31802c4d9155a436f4731064bb8935ea522ff8d8 /dgit-maint-bpo.7.pod | |
parent | 4ebed9cbf04d02915742f95afed7df78cbe6478f (diff) |
dgit-maint-bpo(7): new manpage
Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>
Closes: #857490
Diffstat (limited to 'dgit-maint-bpo.7.pod')
-rw-r--r-- | dgit-maint-bpo.7.pod | 141 |
1 files changed, 141 insertions, 0 deletions
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>. |