[bug#48667] [PATCH] doc: Expound on how to specify the version of a package.

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

Xinglu Chen <public@yoctocell.xyz> writes:

> * doc/guix.texi (package Reference): Describe how packages that lack a release
> or are pinned to an unreleased version should specify the ‘version’ field.
> Add documentation for the ‘git-version’ procedure.

Thanks. 

I don't know if all should be included in the manual (though I think
the `git-version' function definitely should), but I'll comment it a bit
anyway.

>  @item @code{version}
> -The version of the package, as a string.
> +The version of the package, as a string.  If there are no releases of
> +the package, or a unreleased version is desired, the version should
> +contain @code{VERSION-REVISION.COMMIT}.  @code{VERSION} is
> +@c TODO: 0.0.0 or just 0 ?

  @samp{@var{VERSION}-@var{REVISION}.@var{COMMIT}} ... @var{VERSION}...

I think you should drop the "version 0" case altogether. I don't think
enforcing "0" or "0.0.0" does matter, and it adds noise to the
explanations.

> +@code{0.0.0} or whatever the latest version is, and @code{REVISION} is
> +the revision of the Guix package (@code{0} if it is a new package),
> +whenever the package is updated to a newer version the revision should
> +also be bumped.

  @var{REVISION}

I think you need to explain why bumping revision is needed.

Also, this is all specific to hash-based repositories. For example, SVN
uses monotonic revisions already, so none of the above applies to such
packages.

> @code{COMMIT} is the @dfn{commit} or @dfn{changeset}
> +corresponding to the version, it should only contain 7 characters.  If
> +the fetch method is @code{git-fetch} (@pxref{origin Reference}), there
> +is the @code{git-version} procedure that makes it easier to specify the
> +version.

@var{COMMIT}

> +@example
> +(git-version "0.0.0" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
> +@result{} "0.0.0-0.93818c9"
> +@end example
> +@end deffn

Here too, I think the special "0.0.0" case is misleading.

Maybe @lisp is more appropriate than @example.

Regards,
-- 
Nicolas Goaziou