[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[bug#48667] [PATCH] doc: Expound on how to specify the version of a pack
From: |
Xinglu Chen |
Subject: |
[bug#48667] [PATCH] doc: Expound on how to specify the version of a package. |
Date: |
Sun, 06 Jun 2021 11:09:54 +0200 |
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. :)
signature.asc
Description: PGP signature