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

[Xinglu Chen]

On Wed, May 26 2021, Nicolas Goaziou wrote:

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

Makes sense, users can probably that out on their own.

>> +@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.

I am not familiar with SVN, but I will look into it.

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

Good point.

Thanks for the review!

signature.asc
Description: PGP signature