[bug#53163] [PATCH] doc: Document some reasons for/against git tags/commits.

[Maxime Devos]

> I think we should separate reference material from guidelines. 
> Perhaps this should rather go under “Packaging Guidelines”, next to
> “Version Numbers”?

I suppose for consistency with the ‘Packaging Guidelines’ chapter, I
could move it there, though I'd like to add a cross-reference to the
description of ‘commit’ in git-reference for convenience, e.g. maybe:

     ‘commit’
          This string denotes either the commit to fetch (a hexadecimal
          string), or the tag to fetch.  You can also use a “short”
          commit ID or a ‘git describe’ style identifier such as
          ‘v1.0.1-10-g58d7909c97’.  **To decide between choosing a
          commit or a tag, the guidelines in [cross-reference] may be
          useful.**

?

(At first I'd have preferred to not separate reference material to keep
all information on commits together, but on second thought separating
them would be more orderly and it's not like we don't have cross-
references, so maybe it would be better to split ...)

> Toggle quote (4 lines)
> > +Commits make reviewing somewhat trickier, because the reviewer has
> > +to
> > +verify that that the commit actually corresponds to the package
> > version.
> I'd also add a line regarding the difficulty to verify that a commit
> did once belong to a tag as a future reader, but I'm not sure what
> exactly to advise here and how.  In the particular case of minetest,
> we have an external map of "tags" to commits that can be queried, but
> for most repos I fear the tags would simply be lost to time.

FWIW, the same holds (though maybe to a lesser degree in practice?) for
hashes and tarballs), not specific to git.

Anyway, SWH keeps this historical information, e.g. here are two lists
of tags->commits of the Minetest repo at two different points in time:

* 
https://archive.softwareheritage.org/browse/snapshot/d063751724753b97de41a34aa3d1779186530bb4/releases/?origin_url=https://github.com/minetest/minetest&timestamp=2020-01-18T00:07:33Z
* 
https://archive.softwareheritage.org/browse/snapshot/81e0233dbaf285922bef2281f4e5cbbe5fbc7ea0/releases/?origin_url=https://github.com/minetest/minetest&timestamp=2022-06-25T04:01:20Z

That assumes trusting SWH to be correct of course (and a bit of a
SPOF though I don't expect problems), but with some work, things can
be verified even for repos that delete tags.

Anyway, any remaining comments or a second opinion?  (Would like more
than three people for something like this?)

Greetings,
Maxime.

signature.asc
Description: This is a digitally signed message part