Hi Sean
Lovely to see some progress on documenting tag2upload :)
# Git-Tag-Tagger
+Name and e-mail address of the person who made the Git tag from which this
+upload was generated (and to which it corresponds) in accordance with the
+tagging protocol described in the :manpage:`tag2upload(5)` manual page.
+The syntax is the same as for the :ref:`Maintainer field <s-f-Maintainer>`.
+The value comes from the ``tagger`` line of the raw Git tag.
I haven't found any documentation of the format for the 'tagger' field
within the git documentation but I see a comment in
TAG2UPLOAD-DESIGN.txt that the data are reformatted to 'deb822' format.
I'm curious where that format is documented, given neither
deb-control(5) or Policy ยง5.6.2 document it adequately.
I'd like to not create yet more policy that outsources the definition
how to format name+email to a buggy spec that no-one seems keen to fix.
I'm not sure that tag2upload can aim at a Maintainer field spec that is
as rubbery as what we have; fixing Maintainer will require us to
describe some quoting rules and so fixing #401452 might then make
tag2upload insta-buggy - given we don't like making things buggy by
changing policy, perhaps we need to do this the other way around? Before
we bake in this badness in yet another system that we will all come to
rely on and then argue it's too hard to fix, is it reasonable to first
fix #401452? (and all the variations of that bug that are merged even
though perhaps not _quite_ dupes)
# Git-Tag-Info
+Other information about the Git tag from which this upload was generated (and
+to which it corresponds) in accordance with the tagging protocol described in
+the :manpage:`tag2upload(5)` manual page.
+
+The value is of the form ``tag=TAGOBJID fp=FINGERPRINT`` where ``TAGOBJID`` is
+the Git object ID of the Git tag object, and ``FINGERPRINT`` is the
+fingerprint (in hexadecimal, without spaces) of the PGP key used to sign the
+Git tag. Other space-separated ``keyword=value`` items may be introduced in
+the future, and users of this field must ignore items with unknown keywords.
I don't see either of "tag=TAGOBJID" or "fp=FINGERPRINT" in
tag2upload(5) for the version in sid. Are these new fields not yet
documented in that manual? Alternatively, if it wasn't intended to be a
reference to tag2upload(5) for more information, then the wording here
needs improving as I definitely had the impression that was where I
would find more details from the above.
I think that a cross-reference to TAG2UPLOAD-DESIGN.txt is needed in
this section - I spent a while looking at various dgit manuals, git
manuals and the referenced tag2upload(5) before realising that
TAG2UPLOAD-DESIGN.txt existed (that it doesn't appear to be in any
binary package didn't help me btw); I felt that TAG2UPLOAD-DESIGN.txt
was necessary to understand this section.
What is "TAGOBJID" in this situation? This term is used extensively
within the dgit source code but I can't see it in the documentation for
either dgit or git. The only info I found was in TAG2UPLOAD-DESIGN.txt
and I'm afraid that I didn't find that definition enlightening.
How does the "TAGOBJID" differ from the "git commit hash" that is in the
existing Dgit header?
Is TAGOBJID the object id that is output from "git show debian/1.2.3"
and "git tag --verify debian/1.2.3"?
$ apt-cache showsrc dgit | grep Dgit
Dgit: 2a0d4a9840faf2347477c27e7307278a3a7a53d3 debian
archive/debian/12.7 https://git.dgit.debian.org/dgit
$ git show debian/12.7 | grep commit
commit 2a0d4a9840faf2347477c27e7307278a3a7a53d3
$ git tag --verify debian/12.7 | grep ^object
object 2a0d4a9840faf2347477c27e7307278a3a7a53d3
I assume that this is not intended to be redundant information and that
some deeper knowledge of git internals is needed here ... that's fine,
but neither this patch or TAG2UPLOAD-DESIGN.txt tell me what it is or
where to look for that information. (Is this perhaps something like `git
rev-parse debian/12.7`?)
A bit more information on the meaning of these key=value pairs both in
Policy and TAG2UPLOAD-DESIGN.txt would be appreciated. While I have no
intention of reimplementing tag2upload in Python, I can confidently
predict that someone will ask for python-debian's Deb822 module to
expose these fields and probably even provide an interface for
validation; at that stage I'll be looking for a spec that explains these
things, and we're not quite there yet. There are quite a few projects
outside the Debian archive that trawl through our metadata using
python-debian and I can imagine them being interested in these fields.
# Process and procedure
Finally, on a procedural note, I looked at the archive's existing
Sources files and these headers do not appear to be in current use in
Debian. tag2upload is not (publicly) deployed, so that is to be expected.
There have been comments made in the past that Policy was there to
document current practice. Personally, I welcome this as a new normal:
new things where interoperability is important get documented in Policy
first. Given that documenting something with zero current usage is,
perhaps, a departure from how Policy discussions often go, it's likely
worth being explicit that this is what is being done in this case and
that it is acceptable.
thanks
Stuart
--
Stuart Prescott http://www.nanonanonano.net/ stu...@nanonanonano.net
Debian Developer http://www.debian.org/ stu...@debian.org
GPG fingerprint 90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7
