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

From: Liliana Marie Prikler <[email-masked]>
Date: Sun, 09 Jan 2022 22:15:54 +0100

Am Sonntag, dem 09.01.2022 um 19:10 +0000 schrieb Maxime Devos:
> * doc/contributing.texi (Minetest Packages): New section.
> * doc/guix.texi: Copyright update.
> ---
>  doc/contributing.texi | 42
> ++++++++++++++++++++++++++++++++++++++++++
>  doc/guix.texi         |  2 +-
>  2 files changed, 43 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/contributing.texi b/doc/contributing.texi
> index 72f5ce1e0e..5b91fc7867 100644
> --- a/doc/contributing.texi
> +++ b/doc/contributing.texi
> @@ -394,6 +394,7 @@ needed is to review and apply the patch.
>  * Synopses and Descriptions::   Helping users find the right
> package.
>  * Snippets versus Phases::      Whether to use a snippet, or a build
> phase.
>  * Emacs Packages::              Your Elisp fix.
> +* Minetest Packages::           Building blocks.
>  * Python Modules::              A touch of British comedy.
>  * Perl Modules::                Little pearls.
>  * Java Packages::               Coffee break.
> @@ -703,6 +704,47 @@ When encountering problems, it is wise to check
> for the presence of the
>  file, and whether any dependencies and their versions listed therein
> are
>  satisfied.
>  
> +@node Minetest Packages
> +@subsection Minetest Packages
> +@cindex minetest, packaging
> +
> +A Minetest mod @code{foo} is named @code{minetest-foo} -- the author
> +name from ContentDB is not included, unless required to resolve a
> name
> +collision.
> +
> +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?

> +@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. 
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?

Otherwise LGTM.