Re: Summary: Git Packaging Round 2 [comments by 11/05/2019]

[wferi@debian.org]

Sam Hartman <leader@debian.org> writes:

> General Recommendation
> ======================
> [...]
> You should document the branch format (such as patches unapplied (gbp
> pq)) that your repository uses.  Best practice for documenting this is
> still evolving.  The best current option is to document your branch
> format in debian/README.source.

I'm not sure this best current option (README.source) is something I'd
actually recommend.  Granted, it's annoying to have to figure the git
workflows, and a freeform documentation text like README.source helps if
you have to do it a couple of times, but it still isn't a thing you can
automate.  Thus I think that the overall burden it creates outweighs its
value.  Also, from the Policy: "maintainers are encouraged to document
in a debian/README.source file any source package with a particularly
complex or unintuitive source layout or build system" -- do we intend to
recommend something "particularly complex or unintuitive"?

I have to admit I haven't read the full discussion.  Have we got a list
of items we need to know about the "branch format"?  Your text mentions
patches applied or unapplied, which dpkg-source (and, according to you,
dgit) already handles, so a utility could provide the answer if there's
at least one patch in the package; why document it then?  If the
heuristic is deemed too fragile or we want to store this information
even in the absence of patches, perhaps we could invent a new (local)
dpkg-source option to override it and require using that (just an idea).
Another obvious item is the main packaging branch, which is declared by
Vcs-Git ("ideally", says the Policy -- shouldn't we make this stronger?)

If we really want to go beyond these, the next step would be discovering
the actual names of the DEP-14 entities, I guess.  This would probably
start with identifying the tooling (gbp, git-debrebase, git-dpm, etc.)
then reading their configuration (if any).  This would give answers for
the previous items as well.  But do we target mass operations on this
scale of variability at all?

Anyway: I think we should recommend setups which allow reliable
determination of the needed information, thus not requiring manual
textual documentation.
-- 
Thanks,
Feri