Subject: Re: [PATCH 01/13] doc: Give some tips on Minetest packaging.

From: Maxime Devos <[email-masked]>
Date: Mon, 10 Jan 2022 00:29:37 +0100

Liliana Marie Prikler schreef op zo 09-01-2022 om 22:15 [+0100]:
> [...]
> > +
> > +Sometimes, it might be unclear what the version of a Minetest mod
> > is.
> > +For example, ContentDB and the importer reports 2020-01-01, but
> > +according to the forums the version is 2.1.  Usually, in these cases
> > the
> > +version on ContentDB is the newest and intended for distribution. As
> > +such, you can use the version from ContentDB without any special
> > +comments.
> We might want to quote an authoritative resource on that, perhaps in
> the footnote?

Yes, quoting sources seems good.

About newest version: I don't have an authoritive source at hand; this
is more speaking of my own experience of what seems to be the case.  I
could compute some statistics w.r.t. how often is the latest version on
ContentDB >= latest tagged version in the repository (where > is the
is-(indirect)-child-commit-of relation, as the versions strings aren't
always directly comparable -- see discussion about CalVer vs. SemVer
and ContentDB sometimes using CalVer and sometimes SemVer).

This also seems a consequence of ContentDB being the official source
of mods and used by Minetest's built-in installer.

About ‘intended for distribution’: I'll look for a forum post or wiki
page targetting new mod authors that want to distribute their mod.

What do you think of me gathering this information and (if not
falsified) presenting it to upstream in some public location,
asking if it seems about right, and (presuming they answer ‘yes’),
quoting their response?

> > +@c Currently it's always checked out from git, but in principle
> > +@c tarballs could be used.
> > +
> > +Even though the source code is often checked out from version
> > control,
> > +it is not necessary to use @code{git-version} or @code{hg-version}:
> > the
> > +releases on ContentDB are formal releases; in fact they are
> > upstream's
> > +official source of Minetest packages and they are not mutated in-
> > place.
> > +
> > +@c Example (zip): mods by TenPlus1
> > +@c Example (git): basic_materials, ethereal
> > +While ContentDB provides the source code of packages in zip form, it
> > is
> > +recommended not to use these, because users can and do delete old
> > +versions.  Likewise, sometimes the maintainer initially did tag
> > versions
> > +but later stops doing so, breaking @command{guix refresh -u}.  As
> > such,
> > +it is recommended not to use git tags in @code{origin} records and
> > +instead refer to the commit directly.
> This combination of version+commit is something I'd generally
> discourage (my reasoning for doing so already explained elsewhere), so
> to me it might make sense to still explicitly point attention to it. 

That discussion I had in mind while writing this documentation.

I happen to disagree though, being mostly neutral about
version+commit with a slight preference towards including the commit
itself in the commit field of 'git-reference' (and not a tag pointing
to the commit), because it is more explicit and it fits slightly
better in some nebulous plans for decentralising source code
downloading/storage.  There are ‘tricking peer review’ issues
with this though, hence neutral.

(See <https://notabug.org/maximed/rehash> if interested)

Hence, adding something like ‘This is specific to Minetest packages,
for other packages it is advised to use git tags, see [...]’ doesn't
make much sense to me, though I understand why it would make sense
to you.  Furthermore, the reference [...] currently doesn't exist, so I
cannot point the reader to an explanation why for other packages we
want git tags and not commits.

If there was consensus (one way or the other) and some section in the
manual explaining what should usually be used (tags or commits)
(preferably also explaining the reasons and not simply stating things),
I could link to it though.  Or if there's no consensus, and the section
said something like

‘There are two options: tags or commits.  Currently there's no
consensus about what's best.  Here are some pros and cons of each: ...
Due to a lack of consensus, the patch submitter can make the choice.
When in doubt, throw a dice.’ (*) (to be reworded!),

then I could work with that as well.

Perhaps I could write out (*) a bit more, as a separate documentation
patch?  I'd have to ask on guix-devel@ if I'm
understanding/misunderstanding the lack of consensus, and see if
someone has already summarised things, maybe see if Nix people
have thought about this, etc.

> Perhaps setting a package-property such as (upstream . contentdb),
> which would also make it clear why we don't e.g. want the latest-git
> updater to apply?

More generally, being able to explicitely choose the updater
(minetest/github/elpa/...) seems useful!

However, in the context of this documentation section and the changes
to the ContentDB importer, I don't think latest-git is relevant here
(except for the infrequent edge cases like minetest-throwing-arrows and
emacs-next): we almost never want the latest-git updater to apply
(because formal releases etc.).  And when we do want it to apply, we
set

  (with-latest-git-commit . #true/"refs/heads/master"/...)

otherwise latest-git doesn't run.  Well, we don't do that yet except
for minetest-throwing-arrows, but that's the idea.

To summarise, I don't see the value that adding (upstream . contentdb)
would bring, it seems to me that it would only make the package
definitions longer.  Would this package property be pure documentation,
or would it be interpreted by the updater code in some way?

> Otherwise LGTM.

I'm not complaining, but from
<https://lists.gnu.org/archive/html/guix-devel/2021-12/msg00259.html>
and resulting discussion I was kind of expecting that you'd
want me to do

(let ((commit ...)
      (revision ...))
  (package ...
    (version (git-version "contentdb-version" revision commit)) ...)),

though you did write ‘I'd want a comment like the ones I find in
minetest.scm to [...]’ I suppose, and this new documentation is
explaining the reasons for using commits (raw commits in your
terminology) in some detail and for all Minetest packages at once.

Unrelated: git mirrors seem a cool idea!

Greetings,
Maxime