Bug#857490: [PATCH] dgit-maint-bpo(7): new manpage
Sean Whitton writes ("Bug#857490: [PATCH] dgit-maint-bpo(7): new manpage"):
> On Mon 01 Jul 2019 at 12:06pm +0100, Ian Jackson wrote:
> > Possible solutions may include: [...]
>
> I think the best thing to recommend is to use the rebasing backports
> workflow. It is not especially arduous and in some respects elegant.
Fair enough. In my master now.
Of course what's really needed here is git-ffqrebase. backports is a
partial Debian derivative.
--
Ian JacksonThese opinions are my own.
If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.
Bug#857490: [PATCH] dgit-maint-bpo(7): new manpage
Hello, On Mon 01 Jul 2019 at 12:06pm +0100, Ian Jackson wrote: > I took a look at this. > > I think the merging workflow you describe will not go well if the sid > package develops changes to upstream files (through new upstream > version, or through changes to the delta queue). Typically the > package is `3.0 (quilt)', so if there are any changes to the delta > queue, dgit patch linearisation will be needed, and it may well fail > after `git merge'. Good point. I've been using the merge workflow successfully, but probably because none of my backports require additional changes to the upstream source. > Possible solutions may include: [...] I think the best thing to recommend is to use the rebasing backports workflow. It is not especially arduous and in some respects elegant. I've revised the manpage to do that. Updated patch attached. -- Sean Whitton From 7136216ac6ad77eabcfe35e802ea498102150046 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sat, 2 Mar 2019 17:53:39 -0700 Subject: [PATCH] dgit-maint-bpo(7): new manpage Signed-off-by: Sean Whitton --- Makefile | 3 +- dgit-maint-bpo.7.pod | 141 +++ 2 files changed, 143 insertions(+), 1 deletion(-) create mode 100644 dgit-maint-bpo.7.pod diff --git a/Makefile b/Makefile index 380bdb03..c4105640 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 ..e977d258 --- /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
Bug#857490: [PATCH] dgit-maint-bpo(7): new manpage
I took a look at this. I think the merging workflow you describe will not go well if the sid package develops changes to upstream files (through new upstream version, or through changes to the delta queue). Typically the package is `3.0 (quilt)', so if there are any changes to the delta queue, dgit patch linearisation will be needed, and it may well fail after `git merge'. Possible solutions may include: - being the maintainer in sid and knowing what your git workflow and branch format is and doing something workflow-specific - git-debcherry (blocked by #930881) - changing the source format - git-ffqrebase (does not exist yet, #869993) - git-debrebase convert-from-dgit-view may help in some cases; I have used it for security updates with moderate success, but I think repeated conversions may be troublesome Ian. -- Ian JacksonThese opinions are my own. If I emailed you from an address @fyvzl.net or @evade.org.uk, that is a private address which bypasses my fierce spamfilter.
Bug#857490: [PATCH] dgit-maint-bpo(7): new manpage
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 Date: Sat, 2 Mar 2019 17:53:39 -0700 Subject: [PATCH] dgit-maint-bpo(7): new manpage Signed-off-by: Sean Whitton --- 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 ..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 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. + +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, 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 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 +. -- 2.20.1 signature.asc Description: PGP signature
