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

["Ludovic Courtès" <ludo@gnu.org>]

Hi Xinglu,

Xinglu Chen <public@yoctocell.xyz> skribis:

> * 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.

[...]

>  @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 @samp{@var{VERSION}-@var{REVISION}.@var{COMMIT}}.  @var{VERSION}
> +is the version of the package, and @var{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 to reflect
> +the fact that package has been updated.  If the fetch method for the
> +package is @code{git-fetch} or @code{hg-fetch} (@pxref{origin
> +Reference}), @var{COMMIT} should be the @dfn{commit} or @dfn{changeset}
> +corresponding to the version, it should only contain 7 characters.  If
> +the fetch method is @code{git-fetch}, there is the @code{git-version}
> +procedure (see below) that makes it easier to specify the version.
> +Packages which use @code{svn-fetch} or @code{bzr-fetch} should set
> +@var{COMMIT} to the same value as the @code{revision} field in
> +@code{svn-reference} or @code{bzr-reference}.

The text LGTM, but I think “package Reference” is the wrong place for
it: it’s the reference, whereas the text above is a guideline.

The “Version Numbers” section under “Packaging Guidelines” already
touches this topic.  Perhaps we need to expand it and/or link to it from
“package Reference”, like:

  @item @code{version}
  The version of the package, as a string.  @xref{Version Numbers}, for
  guidelines.

The ‘git-version’ procedure could be documented in “Version Numbers”
too.

WDYT?

Thanks,
Ludo’.