control: tag 857490 +patch Hello,
On Sun 06 Jan 2019 at 01:07PM +00, Ian Jackson wrote: >> I also think that dgit could emit a recommendation to look at that >> manpage in the kind of case that prompted me to file this bug. It can >> just look for ~bpoNN in the version number that is missing from >> d/changelog, and output a hint. > > Are you volunteering to write the (7) manpage ? :-) Here is a patch. This does not completely resolve #898494, as I haven't modified dgit to output the hint to look at the manpage. -- Sean Whitton
From 3d3e6c7cf5448ae1c1dd74f1c18ea08ae514a9b6 Mon Sep 17 00:00:00 2001 From: Sean Whitton <spwhit...@spwhitton.name> Date: Sat, 2 Mar 2019 17:53:39 -0700 Subject: [PATCH] dgit-maint-bpo(7): new manpage Signed-off-by: Sean Whitton <spwhit...@spwhitton.name> --- Makefile | 3 +- dgit-maint-bpo.7.pod | 133 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 135 insertions(+), 1 deletion(-) create mode 100644 dgit-maint-bpo.7.pod diff --git a/Makefile b/Makefile index 7d0c422f..3fce578c 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..ff879a45 --- /dev/null +++ b/dgit-maint-bpo.7.pod @@ -0,0 +1,133 @@ +=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. + +Whether you use a merging or rebasing backports workflow is, so far as +the author of this manpage can tell, simply a matter of personal +preference. There are good arguments in favour of both workflows +fitting the semantics of the B<*-backports> suites. + +=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 + +=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 +<spwhit...@spwhitton.name>. -- 2.20.1
signature.asc
Description: PGP signature
