Sam Hartman <lea...@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
