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.  :)