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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 48667 in the body.
You can then email your comments to 48667 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Xinglu Chen <public <at> yoctocell.xyz>
To: guix-patches <at> gnu.org
Subject: [PATCH] doc: Expound on how to specify the version of a package.
Date: Wed, 26 May 2021 11:00:25 +0200

* 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.
---
I am unsure if the format for packages that don’t have a release should
be ‘0.0.0-REVISION.COMMIT’ or just ‘0-REVISION.COMMIT’.

 doc/guix.texi | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index e8b0485f78..083f65c9c5 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -89,6 +89,7 @@ Copyright @copyright{} 2020 Jonathan Brielmaier@*
 Copyright @copyright{} 2020 Edgar Vincent@*
 Copyright @copyright{} 2021 Maxime Devos@*
 Copyright @copyright{} 2021 B. Wilson@*
+Copyright @copyright{} 2021 Xinglu Chen@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -6651,7 +6652,18 @@ This is the data type representing a package recipe.
 The name of the package, as a string.
 
 @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 ?
+@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.  @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.
 
 @item @code{source}
 An object telling how the source code for the package should be
@@ -6757,6 +6769,15 @@ automatically corrected.
 @end table
 @end deftp
 
+@deffn {Scheme Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
+Return the version string for packages using @code{git-fetch}.
+
+@example
+(git-version "0.0.0" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
+@result{} "0.0.0-0.93818c9"
+@end example
+@end deffn
+
 @deffn {Scheme Syntax} this-package
 When used in the @emph{lexical scope} of a package field definition, this
 identifier resolves to the package being defined.

base-commit: 3f2a4b098039bd374c76d524223de3c6c475f23e
-- 
2.31.1

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

From: Nicolas Goaziou <mail <at> nicolasgoaziou.fr>
To: Xinglu Chen <public <at> yoctocell.xyz>
Cc: 48667 <at> debbugs.gnu.org
Subject: Re: [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

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

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

[Message part 1 (text/plain, inline)]

On Wed, May 26 2021, Nicolas Goaziou wrote:

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

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 (application/pgp-signature, inline)]

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

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

* 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.
---
Changes since v1:
* Remove the case for “version 0”.

* Use @var{} instead of @code{} when appropriate, and @lisp instead of
  @example.

* Be more specific about what to set COMMIT to.  Git/Mercurial and
  SVN/Bzr should be handled differently.

 doc/guix.texi | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index e8b0485f78..9338136ebe 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -89,6 +89,7 @@ Copyright @copyright{} 2020 Jonathan Brielmaier@*
 Copyright @copyright{} 2020 Edgar Vincent@*
 Copyright @copyright{} 2021 Maxime Devos@*
 Copyright @copyright{} 2021 B. Wilson@*
+Copyright @copyright{} 2021 Xinglu Chen@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -6651,7 +6652,21 @@ This is the data type representing a package recipe.
 The name of the package, as a string.
 
 @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}.
 
 @item @code{source}
 An object telling how the source code for the package should be
@@ -6757,6 +6772,15 @@ automatically corrected.
 @end table
 @end deftp
 
+@deffn {Scheme Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
+Return the version string for packages using @code{git-fetch}.
+
+@lisp
+(git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
+@result{} "0.2.3-0.93818c9"
+@end lisp
+@end deffn
+
 @deffn {Scheme Syntax} this-package
 When used in the @emph{lexical scope} of a package field definition, this
 identifier resolves to the package being defined.

base-commit: 3f2a4b098039bd374c76d524223de3c6c475f23e
-- 
2.31.1

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

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

From: Xinglu Chen <public <at> yoctocell.xyz>
To: Ludovic Courtès <ludo <at> gnu.org>
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: Sun, 06 Jun 2021 11:09:54 +0200

[Message part 1 (text/plain, inline)]

On Sat, Jun 05 2021, Ludovic Courtès wrote:

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

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 (application/pgp-signature, inline)]

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

From: Xinglu Chen <public <at> yoctocell.xyz>
To: 48667 <at> debbugs.gnu.org
Cc: Ludovic Courtès <ludo <at> gnu.org>
Subject: [PATCH] doc: Add reference for ‘git-ver
Date: Sun, 06 Jun 2021 11:19:37 +0200

* doc/contributing.texi (Version Numbers): Document ‘git-version’ and
  ‘hg-version’.
* doc/guix.texi (package Reference): Reference ‘Version Numbers’ section for
  version naming guidelines.
---
 doc/contributing.texi | 22 +++++++++++++++++++---
 doc/guix.texi         |  4 +++-
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 87719a4bbe..ee6cb97c8d 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -532,9 +532,11 @@ It is a good idea to strip commit identifiers in the @code{version}
 field to, say, 7 digits.  It avoids an aesthetic annoyance (assuming
 aesthetics have a role to play here) as well as problems related to OS
 limits such as the maximum shebang length (127 bytes for the Linux
-kernel).  It is best to use the full commit identifiers in
-@code{origin}s, though, to avoid ambiguities.  A typical package
-definition may look like this:
+kernel).  There are helper functions for doing this for packages using
+@code{git-fetch} or @code{hg-fetch} (see below).  It is best to use the
+full commit identifiers in @code{origin}s, though, to avoid ambiguities.
+A typical package definition may look like this:
+
 
 @lisp
 (define my-package
@@ -553,6 +555,20 @@ definition may look like this:
       )))
 @end lisp
 
+@deffn {Scheme Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
+Return the version string for packages using @code{git-fetch}.
+
+@lisp
+(git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
+@result{} "0.2.3-0.93818c9"
+@end lisp
+@end deffn
+
+@deffn {Scheme Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET}
+Return the version string for packages using @code{hg-fetch}.  It works
+in the same was @code{git-version}
+@end deffn
+
 @node Synopses and Descriptions
 @subsection Synopses and Descriptions
 
diff --git a/doc/guix.texi b/doc/guix.texi
index eb64518a95..e71ec70859 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -89,6 +89,7 @@ Copyright @copyright{} 2020 Jonathan Brielmaier@*
 Copyright @copyright{} 2020 Edgar Vincent@*
 Copyright @copyright{} 2021 Maxime Devos@*
 Copyright @copyright{} 2021 B. Wilson@*
+Copyright @copyright{} 2021 Xinglu Chen@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -6657,7 +6658,8 @@ This is the data type representing a package recipe.
 The name of the package, as a string.
 
 @item @code{version}
-The version of the package, as a string.
+The version of the package, as a string.  @xref{Version Numbers}, for
+guidelines.
 
 @item @code{source}
 An object telling how the source code for the package should be

base-commit: 9caf7112ee50af26fbc4c1bd3c337f1f86b710af
-- 
2.31.1

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

From: Maxime Devos <maximedevos <at> telenet.be>
To: Xinglu Chen <public <at> yoctocell.xyz>, 48667 <at> debbugs.gnu.org
Cc: Ludovic Courtès <ludo <at> gnu.org>
Subject: Re: [bug#48667] [PATCH] doc: Add reference for
 ‘git-ver
Date: Sun, 06 Jun 2021 11:48:25 +0200

[Message part 1 (text/plain, inline)]

Xinglu Chen schreef op zo 06-06-2021 om 11:19 [+0200]:
> +@deffn {Scheme Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
> +Return the version string for packages using @code{git-fetch}.
> +
> +@lisp
> +(git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
> +@result{} "0.2.3-0.93818c9"
> +@end lisp
> +@end deffn
> +
> +@deffn {Scheme Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET}
> +Return the version string for packages using @code{hg-fetch}.  It works
> +in the same was @code{git-version}
> +@end deffn

Linguistic nitpick: about ‘It works in the same was @code{git-version}’: ‘in the same was’
seems ungrammatical to me. Should this have been something like

   It works in the same way as @code{git-version}.

? (Remember to include the period.)

LGTM otherwise.

Greetings,
Maxime.

[signature.asc (application/pgp-signature, inline)]

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

From: Xinglu Chen <public <at> yoctocell.xyz>
To: Maxime Devos <maximedevos <at> telenet.be>, 48667 <at> debbugs.gnu.org
Cc: Ludovic Courtès <ludo <at> gnu.org>
Subject: Re: [bug#48667] [PATCH] doc: Add reference for
 ‘git-ver
Date: Sun, 06 Jun 2021 12:33:45 +0200

[Message part 1 (text/plain, inline)]

On Sun, Jun 06 2021, Maxime Devos wrote:

> Xinglu Chen schreef op zo 06-06-2021 om 11:19 [+0200]:
>> +@deffn {Scheme Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
>> +Return the version string for packages using @code{git-fetch}.
>> +
>> +@lisp
>> +(git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
>> +@result{} "0.2.3-0.93818c9"
>> +@end lisp
>> +@end deffn
>> +
>> +@deffn {Scheme Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET}
>> +Return the version string for packages using @code{hg-fetch}.  It works
>> +in the same was @code{git-version}
>> +@end deffn
>
> Linguistic nitpick: about ‘It works in the same was @code{git-version}’: ‘in the same was’
> seems ungrammatical to me. Should this have been something like
>
>    It works in the same way as @code{git-version}.
>
> ? (Remember to include the period.)

Indeed, I must have made a silly typo.

[signature.asc (application/pgp-signature, inline)]

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

From: Xinglu Chen <public <at> yoctocell.xyz>
To: 48667 <at> debbugs.gnu.org
Cc: Ludovic Courtès <ludo <at> gnu.org>,
 Maxime Devos <maximedevos <at> telenet.be>
Subject: [PATCH v2] doc: Add refernece for ‘git-version’ and ‘hg-version’.
Date: Sun, 06 Jun 2021 12:37:23 +0200

* doc/contributing.texi (Version Numbers): Document ‘git-version’ and
  ‘hg-version’.
* doc/guix.texi (package Reference): Reference ‘Version Numbers’ section for
  version naming guidelines.
---
Changes since v2:

* Fix typos

 doc/contributing.texi | 22 +++++++++++++++++++---
 doc/guix.texi         |  4 +++-
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 87719a4bbe..3e2a9c8d2f 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -532,9 +532,11 @@ It is a good idea to strip commit identifiers in the @code{version}
 field to, say, 7 digits.  It avoids an aesthetic annoyance (assuming
 aesthetics have a role to play here) as well as problems related to OS
 limits such as the maximum shebang length (127 bytes for the Linux
-kernel).  It is best to use the full commit identifiers in
-@code{origin}s, though, to avoid ambiguities.  A typical package
-definition may look like this:
+kernel).  There are helper functions for doing this for packages using
+@code{git-fetch} or @code{hg-fetch} (see below).  It is best to use the
+full commit identifiers in @code{origin}s, though, to avoid ambiguities.
+A typical package definition may look like this:
+
 
 @lisp
 (define my-package
@@ -553,6 +555,20 @@ definition may look like this:
       )))
 @end lisp
 
+@deffn {Scheme Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
+Return the version string for packages using @code{git-fetch}.
+
+@lisp
+(git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
+@result{} "0.2.3-0.93818c9"
+@end lisp
+@end deffn
+
+@deffn {Scheme Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET}
+Return the version string for packages using @code{hg-fetch}.  It works
+in the same way as @code{git-version}.
+@end deffn
+
 @node Synopses and Descriptions
 @subsection Synopses and Descriptions
 
diff --git a/doc/guix.texi b/doc/guix.texi
index eb64518a95..e71ec70859 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -89,6 +89,7 @@ Copyright @copyright{} 2020 Jonathan Brielmaier@*
 Copyright @copyright{} 2020 Edgar Vincent@*
 Copyright @copyright{} 2021 Maxime Devos@*
 Copyright @copyright{} 2021 B. Wilson@*
+Copyright @copyright{} 2021 Xinglu Chen@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -6657,7 +6658,8 @@ This is the data type representing a package recipe.
 The name of the package, as a string.
 
 @item @code{version}
-The version of the package, as a string.
+The version of the package, as a string.  @xref{Version Numbers}, for
+guidelines.
 
 @item @code{source}
 An object telling how the source code for the package should be

base-commit: 9caf7112ee50af26fbc4c1bd3c337f1f86b710af
-- 
2.31.1

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

From: Ludovic Courtès <ludo <at> gnu.org>
To: Xinglu Chen <public <at> yoctocell.xyz>
Cc: 48667-done <at> debbugs.gnu.org, Maxime Devos <maximedevos <at> telenet.be>
Subject: Re: [PATCH v2] doc: Add refernece for ‘git-version’ and ‘hg-version’.
Date: Sun, 06 Jun 2021 14:36:43 +0200

Hi,

Xinglu Chen <public <at> yoctocell.xyz> skribis:

> * doc/contributing.texi (Version Numbers): Document ‘git-version’ and
>   ‘hg-version’.
> * doc/guix.texi (package Reference): Reference ‘Version Numbers’ section for
>   version naming guidelines.

Applied; thanks to the two of you!

Ludo’.

Previous Next

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