How about this. Comments interleaved: @@ -23,7 +23,9 @@ the usefulness of the raw Debian source package. The Debian archive is thought of as an output format.
For example, we don't spend time curating a series of quilt patches. -However, the information such a series would contain is readily +However, +in straightforward cases, +the information such a series would contain is readily available from B<dgit-repos>. This sentence wasn't quite true (as Daniel points out) without qualification. =item @@ -34,6 +36,17 @@ that upstream makes available for download. =back +This workflow is less suitable for some packages. +When the Debian delta contains multiple pieces which interact, +or which you aren't going to be able to upstream soon, +it might be preferable to +maintain the delta as a rebasing patch series, This part is from the most recent suggestion, from Daniel. I suggest adding this part... +to facilitate +reviewing/upstreaming/dropping +individual pieces. ... because I agreed with Daniel's point about rationales. +For such a workflow see for example +dgit-maint-gbp(7). And I think a cross-reference is helpful here so the advice isn't a dead-end. -The Debian packaging of foo is maintained using dgit. For the sake of -an efficient workflow, Debian modifications to the upstream source are -squashed into a single diff, rather than a series of quilt patches. -To obtain a patch queue for package version 1.2.3-1: +The Debian packaging of foo is maintained in git, +using the merging workflow described in dgit-maint-merge(7). +An automatically generated representation of the Debian changes follows. This is from Sean's lates suggestion, except that +A detailed break down of these changes is available from their +canonical representation - +git commits in the packaging repository. I have changed the punctation, and written `git commits' rather than just `commits'. I think this is clearer. +For example, to see the changes made by the Debian maintainer in the +first upload of upstream version 1.2.3, you could use: =over 4 - # apt-get install dgit - % dgit clone foo + % git clone https://git.dgit.debian.org/ % cd foo % git log --oneline 1.2.3..debian/1.2.3-1 -- . ':!debian' =back -See dgit(1), dgit(7) and dgit-maint-merge(7) for more information. +See dgit-maint-merge(7) for more information. If we are advising people to use git clone, they don't need to read the dgit docs. But: +(If you have dgit, use dgit clone foo, +rather than plain git clone.) Sean writes: > I don't think the `dgit clone` need be given since the `git clone` will > contain git.dgit.debian.org, so anyone even slightly familiar with dgit > will know they can use `dgit clone` if they want to. I don't think they will necessarily know that it's advisable. There are a two reasons I can think of why `dgit clone' is better: * It will include changes made in non-dgit-based uploads (eg NMUs). I hope that non-dgit users who read about `the packaging repository' will realise that it may not contain out-of-workflow uploads such as (some) NMUs. But dgit users might assume that it does. I hope that an imprecation to use dgit where available, without a rationale, will suffice. * dgit sets up trees somewhat differently; a dgit user will probably want the effects of `dgit setup-*' which are implied by `dgit clone'. Opinions ? (I have included the complete diff as an attachment.) Ian.
diff --git a/dgit-maint-merge.7.pod b/dgit-maint-merge.7.pod index 5b425b55..47ac4a07 100644 --- a/dgit-maint-merge.7.pod +++ b/dgit-maint-merge.7.pod @@ -23,7 +23,9 @@ the usefulness of the raw Debian source package. The Debian archive is thought of as an output format. For example, we don't spend time curating a series of quilt patches. -However, the information such a series would contain is readily +However, +in straightforward cases, +the information such a series would contain is readily available from B<dgit-repos>. =item @@ -34,6 +36,17 @@ that upstream makes available for download. =back +This workflow is less suitable for some packages. +When the Debian delta contains multiple pieces which interact, +or which you aren't going to be able to upstream soon, +it might be preferable to +maintain the delta as a rebasing patch series, +to facilitate +reviewing/upstreaming/dropping +individual pieces. +For such a workflow see for example +dgit-maint-gbp(7). + =head1 INITIAL DEBIANISATION This section explains how to start using this workflow with a new @@ -230,21 +243,27 @@ changes to the upstream source: =over 4 -The Debian packaging of foo is maintained using dgit. For the sake of -an efficient workflow, Debian modifications to the upstream source are -squashed into a single diff, rather than a series of quilt patches. -To obtain a patch queue for package version 1.2.3-1: +The Debian packaging of foo is maintained in git, +using the merging workflow described in dgit-maint-merge(7). +An automatically generated representation of the Debian changes follows. + +A detailed break down of these changes is available from their +canonical representation - +git commits in the packaging repository. +For example, to see the changes made by the Debian maintainer in the +first upload of upstream version 1.2.3, you could use: =over 4 - # apt-get install dgit - % dgit clone foo + % git clone https://git.dgit.debian.org/ % cd foo % git log --oneline 1.2.3..debian/1.2.3-1 -- . ':!debian' =back -See dgit(1), dgit(7) and dgit-maint-merge(7) for more information. +See dgit-maint-merge(7) for more information. +(If you have dgit, use dgit clone foo, +rather than plain git clone.) =back
-- Ian Jackson <ijack...@chiark.greenend.org.uk> These 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.
