Hello, On Sat 01 Mar 2025 at 03:23pm +11, Stuart Prescott wrote:
> Lovely to see some progress on documenting tag2upload :) And thank you for your feedback! 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. > 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. Frankly, I'm not willing to block documenting these new fields on that really thorny issue. It just makes Policy less useful to readers. > 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.) > 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. And the Git UI is trying to be helpful here in which ways which obscure the data structures actually 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. > 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. I'm glad to hear doing this now all makes sense to you! I don't think that we're doing something different to what we've done before, however -- one reason for waiting for things to appear in the archive is that then their final form gets nailed down before we try to write it down. In this case, however, we did all the design for tag2upload up front, so we can go ahead and document it now. -- Sean Whitton
signature.asc
Description: PGP signature
