control: clone 851897 -1 control: retitle 851897 dgit-maint-merge(7): Improvements to d/source/patch-header control: retitle -1 dgit-maint-merge(7): Explain when workflow is unsuitable
Hello Daniel,
On Sat, Jan 21, 2017 at 10:34:38AM +0000, Daniel Shahaf wrote:
> Thanks for raising this question.
> [...]
> I have two criticisms of this text:
>
> 1. That 'git log' command does not, strictly speaking, produce a patch
> queue. It produces a history of all relevant commits, but that history
> is not a patch queue, since a single logical change may span two or
> more commits (due to a mistake in the first commit, or due to an
> upstream release necessitating extending a previous, not-yet-upstreamed
> change).
Agreed, it shouldn't use the "patch queue" language.
> 2. This text can be interpreted as "If you want to see a patch queue,
> you have to use the same tools the maintainer chose to use" — which
> sounds like a vendor standard. Simply giving a standard 'git clone'
> command would go a long way towards avoiding that impression.
Excellent point.
> I'd also reword without "squashed" (which implies the generated source
> package is an inferior representation), e.g., —
Well, it /is/ an inferior representation -- that's a trade-off that
someone using dgit-maint-merge(7) has consciously made.
However, since there is exactly one diff in d/patches, it's probably
superfluous to talk about anything being squashed, as you suggest.
> The Debian packaging of foo is maintained using dgit, using the
> dgit-maint-merge(7) merge-based workflow. The Debian changes follow.
> For a detailed history, refer to the canonical representation of the
> Debian changes in the `...' branch of the packaging repository:
> .
> git clone bar://.../foo.git
> cd foo
> git log --oneline 1.2.3..debian/1.2.3-1 -- . ':!debian'
>
> This could use a bit of wordsmithing. The 'dgit clone' incantation
> could be given too, alongside the 'git clone', for readers who do
> have/know dgit already.
The reference to the "canonical representation of the Debian changes" is
good.
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.
> The point that should be sold to readers is that there is no patch
> queue in the source package because there isn't a patch queue in the
> workflow (point #1); i.e.: the source package is the best possible
> representation, within the constraints of the "3.0 (quilt)" format, of
> what the maintainer has. I'm not entirely sure, however, whether the
> suggested text would sell that point to an uninformed reader, since
> I'm myself informed — both about dgit specifically (now) and about
> merge/rebase workflows in general.
Right. It's hard to get this point across without cramming too much
into the patch header.
Here is my attempt (in perl's pod format so it can be swiftly converted
into an actual patch against dgit). What do you think?
=head2 Sample text for debian/source/patch-header
It is a good idea to explain how a user can obtain a break down of the
changes to the upstream source:
=over 4
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: 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
% git clone https://git.dgit.debian.org/foo
% cd foo
% git log --oneline 1.2.3..debian/1.2.3-1 -- . ':!debian'
=back
=back
Alternatively, this text could be added to README.source. However,
this might distract from more important information present in the
latter file.
--
Sean Whitton
signature.asc
Description: PGP signature
