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

Previous Next

Full log

Message #17 received at 48667 <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: Xinglu Chen <public <at> yoctocell.xyz>
Cc: 48667 <at> debbugs.gnu.org, Nicolas Goaziou <mail <at> nicolasgoaziou.fr>
Subject: Re: bug#48667: [PATCH] doc: Expound on how to specify the version
 of a package.
Date: Sat, 05 Jun 2021 22:29:05 +0200

Hi Xinglu,

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

Previous Next

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