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

Previous Next

Full log

View this message in rfc822 format

From: Nicolas Goaziou <mail <at> nicolasgoaziou.fr>
To: Xinglu Chen <public <at> yoctocell.xyz>
Cc: 48667 <at> debbugs.gnu.org
Subject: [bug#48667] [PATCH] doc: Expound on how to specify the version of a package.
Date: Wed, 26 May 2021 15:06:45 +0200

Hello,

Xinglu Chen <public <at> 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.

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

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

Regards,
-- 
Nicolas Goaziou

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.