Issues in the Patch Tagging Guidelines
Hi!
Lately I've been updating metadata in patches in packages I maintain and
noticed several issues with the Patch Tagging Guidelines, and after Lucas
created the new great patches UDD service [P] and we discussed some
other issues there, it looked like the guidelines could do with some
fixes and updates.
[P] <https://udd.debian.org/patches.cgi> also part of DMD.
The following list are some of the issues or things that might deserve
to be clarified, fixed or updated (for reference the current guidelines
can be found at <https://dep.debian.net/deps/dep3>):
* dpatch complicates parsing, it is deprecated, probably worth dropping
support for it.
* Although the guidelines seem to intend for git formatted patches to be
supported, the actual specification of the format is not very clear
on its usage and a strict reading does not really allow it.
- There is a requirement for the first field to appear on the first
line, but git formatted patches start with «From ».
- You cannot easily add custom Patch Guideline patches into the first
git stanza, those need to go into the git trailers in the commit
message, separated by whatever text is found in the description,
which does not follow the deb822 format.
- Having to store the patch guideline fields in git commit trailer
fields might mean these pollute the patch which might need to be
removed before submitting upstream.
* Forwarded does not support recording it being sent to an email address.
Not all upstreams have a public mailing list or web site to file reports
or send comments to, and it might be worth allowing a mailto: reference,
or simply an email address.
* Forwarded lists "yes" as a valid implicit value, but does not make it
clear whether an explicit one should be supported. If a mailto: or
email is accepted then this is probably less of an issue. I've also
used this value when I have sent the patch upstream and it has been
applied before I have gotten around to updating the patch metadata,
but I guess at that point not providing the field would also be
fine.
* Forwarded fuzzy specification means parsing its values is rather hard,
see UDD <https://lists.debian.org/debian-qa/2023/01/msg00022.html>.
It would be better to be strict here. In general choosing to be
fuzzy about the whole specification with the intent to help humans,
I think means that programs have a hard time (see UDD above, and
lintian, where both disagree on semantics) and even humans can get
more confused when crafting or parsing them.
* It is not clear, but I think «Origin: vendor» should be clarified to
state that the actual vendor name should be included if there is no
other reference (such as an URL) as in say «Origin: vendor, Debian»?
Otherwise an undefined vendor is not really distinguishable from the
«other» value as it could be any vendor. Also because if a «vendor»
maintainer has created the patch then there might be no URL to point
to except for the VCS it is kept in (if any at all).
* For Applied-Upstream it is not easy to predict what will be the
future upstream version that the patch will be included in. I've opted
for stuff like «3.2.1+, commit:<id>» when 3.2.1 is the last release,
but that does not seem optimal.
* The git Date field could somehow be used in place of Last-Update (even
though the Committer Date instead of the Author Date is what matches
here more closely, but which is not available from «git format-patch»).
* Add new metadata to track single-debian-patch autogenerated patches,
perhaps a new «Autogenerated: yes» or perhaps better something like
«Origin: autogenerated, by:dpkg-source» (or similar descriptive thing)?
These should in general not be warned as needing to be forwarded
upstream, at least not as-is (dpkg-source in 1.22.0 will add a
«Forwarded: not-needed» for these though).
* The language could use some clarification and standardize on the field
and stanza naming used in other parts of the deb822 ecosystem instead
of headers and sets of headers and similar.
This is my current list, Lucas (CCed) probably has other stuff.
Thanks,
Guillem
Reply to: