Hi Sean
Btw, I didn't know you were a maintainer of a deb822 parser.
It might have helped me understand your concerns better if you'd
mentioned that at the outset.
Perhaps, but I actually don't think that's relevant to the comments.
We're discussing the accuracy of the documentation of the format, which
is a bit orthogonal to the who and why someone would look at the format.
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)
This is I wrote "the value comes from the tagger line in the raw Git
tag" so it's unambiguous what is going on.
I disagree. There's a very interesting ambiguity here...
"comes from" is language that would often imply transformation, and
indeed TAG2UPLOAD-DESIGN.txt states quite clearly that the value used is
*not* the raw data from the `tagger` line but that the data is
transformed in some way:
Git-Tag-Tagger: Firstname Surname <email@address>
"tagger" line from the git tag converted to deb822 format
So...
- Is the line exactly what is in the `tagger` line?
- Or is it being transformed? and if it is transformed, how?
The patch for Policy and TAG2UPLOAD-DESIGN.txt (and the implementation!)
need to be consistent on this. I would also say that the "comes from"
wording can be improved regardless of which of the two options above is
the case.
Frankly, I'm not willing to block documenting these new fields on that
really thorny issue. It just makes Policy less useful to readers.
The tagger line appears to be the raw concatenation of
GIT_COMMITTER_NAME <GIT_COMMITTER_EMAIL> with no quoting rules on the name.
That would mean that as soon as #401452 is fixed by specifying some
quoting rules, then tag2upload will also need fixing. As long as we're
not going to baulk at fixing that part of policy because of that, that's ok.
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.
You're right, it's TAG2UPLOAD-DESIGN.txt that specifies this, not
tag2upload(5), because the latter is only about the Git tag format, not
the .changes and .dsc fields.
I could add a footnote with a pointer to TAG2UPLOAD-DESIGN.txt ?
(Probably by first installing it to /usr/share/doc.)
That would be an excellent idea. It could also be referenced on salsa,
of course.
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
It's the ID of the tag object, not the ID of a commit object at which
the tag object points. All these commands are showing you the ID of the
commit object, I believe (haven't checked).
The text is not ambiguous, just perhaps not too helpful if you haven't
had to make these distinctions before.
Having poked at this some more, you are (of course) correct that an
annotated tag has an additional tag object. For those who want to play,
`git cat-file tag mytag` is what you want here; note that `mytag` needs
to be an annotated tag.
I would, however, reject that claim that the text is not ambiguous as
TAGOBJID is defined nowhere in policy, TAG2UPLOAD-DESIGN.txt, the dgit
documentation, dgit source code, git documentation, or even in the git
source code. The only mentions of a TAGOBJID I can find anywhere are in
the gitk and cgit source code and that's not a source of normative
definition for policy. It's fine to make up terms for the purposes of
documentation but when it's not a well-known term, it cannot be used
without some definition somewhere.
And the Git UI is trying to be helpful here in which ways which obscure
the data structures actually present.
That is indeed true. Policy doesn't need to contain a lesson in git
internals, but also can't just make up new terms and leave them
undefined as this patch does at present.
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`?)
It sounds like I could add a note saying something like
Tag objects have distinct IDs from the IDs of the commits to which
they point. Many git commands on operating on tags dereference the
tag immediately, and show you the ID of the commit object and not of
the tag object, but these are not the same.
For the sake of brevity in policy, this could be outsourced to
tag2upload(5) or TAG2UPLOAD-DESIGN.txt - that would be fine, since
you're planning to include those cross references.
I'd add to your wording that the text is defining `TAGOBJID` - being
explicit is useful, particularly since TAGOBJID is going to be difficult
to parse for a non-native English speaker or with screen readers etc.
Best not assume folks can get from "Tag objects have distinct IDs" to
"TAGOBJID".
I'd also suggest the keyword _annotated_ is included in there - from
what I can see, this property is only for annotated tags and so folks
just poking at git tags to understand what is going on won't see these
details. tag2upload is, of course, using signed tags which, by
definition, are annotated tags. A hint to looking at `git cat-file tag
debian/1.2.3-1` would also be handy, perhaps.
cheers
Stuart
--
Stuart Prescott http://www.nanonanonano.net/ [email protected]
Debian Developer http://www.debian.org/ [email protected]
GPG fingerprint 90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7
