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

* 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.
---
Changes since v1:
* Remove the case for “version 0”.

* Use @var{} instead of @code{} when appropriate, and @lisp instead of
  @example.

* Be more specific about what to set COMMIT to.  Git/Mercurial and
  SVN/Bzr should be handled differently.

 doc/guix.texi | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)


base-commit: 3f2a4b098039bd374c76d524223de3c6c475f23e

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

On Sat, Jun 05 2021, Ludovic Courtès wrote:

> 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?

Ah, I totally missed the “Version Numbers” section, it looks like it
already all the information I was looking for.  Since ‘hg-version’ was
just added, I will mention it as well.  :)