Ian Jackson wrote on Sat, Jan 21, 2017 at 18:21:04 +0000:
> 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.
*nod* The target audience here is the package maintainer and this
phrasing hints at the trade-offs between the merge and patch queue
workflows.
> +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.
+1
> -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.
>
The language "automatically generated representation" raises the
"inferior representation" v. "best possible representation in the
format" question again. (mentioned in my previous email)
How about:
The Debian packaging of foo is maintained in git,
using the merging workflow described in dgit-maint-merge(7).
That workflow does not have a patch queue that can be represented
as a quilt series.
A detailed breakdown of the Debian changes is available from…
.
An automatically generated representation of the same changes follows.
[lines 3-4 are new]
A bit verbose, maybe, but hopefully unambiguous.
> 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.
>
It is clearer, yes.
Editorials: s/break down/breakdown/; s/-/:/ (as Sean had).
> 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.
They should, yes; the way Debian is set up, debcheckout may miss NMUs.
(Come to think of it, debcheckout(1) could compare the revision in
changelog to what's in sid and warn if sid is newer... Something along
the lines of
debcheckout() {
local package="$1"
command debcheckout "$1"
if ! dpkg --compare-versions \
$(cd $1*/debian/changelog(:h:h) && dpkg-parsechangeloeg -SVersion) \
ge \
$(rmadison "$1" | grep -w sid | tail -1 | cut ...);
then
echo >&2 "debcheckout: warning: ..."
fi
}
)
Cheers,
Daniel
