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

DoneSubmitted by Xinglu Chen.
Details
4 participants
  • Ludovic Courtès
  • Nicolas Goaziou
  • Maxime Devos
  • Xinglu Chen
Owner
unassigned
Severity
normal
X
X
Xinglu Chen wrote on 26 May 11:00 +0200
(address . guix-patches@gnu.org)
06217762b07f95d2ba2d40277d010647a926df68.1622019402.git.public@yoctocell.xyz
* doc/guix.texi (package Reference): Describe how packages that lack a releaseor 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 shouldbe ‘0.0.0-REVISION.COMMIT’ or just ‘0-REVISION.COMMIT’.
doc/guix.texi | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-)
Toggle diff (52 lines)diff --git a/doc/guix.texi b/doc/guix.texiindex 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
N
N
Nicolas Goaziou wrote on 26 May 15:06 +0200
(name . Xinglu Chen)(address . public@yoctocell.xyz)(address . 48667@debbugs.gnu.org)
87tumphcey.fsf@nicolasgoaziou.fr
Hello,
Xinglu Chen <public@yoctocell.xyz> writes:
Toggle quote (4 lines)> * 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 thinkthe `git-version' function definitely should), but I'll comment it a bitanyway.
Toggle quote (7 lines)> @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 thinkenforcing "0" or "0.0.0" does matter, and it adds noise to theexplanations.
Toggle quote (5 lines)> +@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, SVNuses monotonic revisions already, so none of the above applies to suchpackages.
Toggle quote (6 lines)> @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}
Toggle quote (6 lines)> +@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
X
X
Xinglu Chen wrote on 26 May 16:07 +0200
(name . Nicolas Goaziou)(address . mail@nicolasgoaziou.fr)(address . 48667@debbugs.gnu.org)
874kepy4ec.fsf@yoctocell.xyz
On Wed, May 26 2021, Nicolas Goaziou wrote:
Toggle quote (27 lines)> 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.
Toggle quote (13 lines)>> +@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.
Toggle quote (18 lines)>> @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!
-----BEGIN PGP SIGNATURE-----
iQJJBAEBCAAzFiEEAVhh4yyK5+SEykIzrPUJmaL7XHkFAmCuVjsVHHB1YmxpY0B5b2N0b2NlbGwueHl6AAoJEKz1CZmi+1x5eYEP/2UKukDv1Nm9eUGuwdtU5Svs2ZPnf+K7LFpzuijRzCbPPxKrf0vy6QBhLHJDjR6kuUkfgsApj4Bhy5coDxTIvM31EN4Saoo8rMeIyQx6mtNjxBD5stRt7ABVmcnavVGS0hb6Jbkvddwkj5tB6k1cadnYf3TRQKkl+CSCGS2my7b4l9+2tFSw+AAkkTLJz9pYOjt63fZIlOH/R6lJZCXRfCuPBXrEFxiCoCSFnUmb0YRBTb/SKDolBM+DreTP4cUyU/ksMCPjC01vX6rEH2EU5RBMjZ5IlOZWrraLD2NCRR3s26G2Mke0X66n7usfOHG5bHtOp5WQY7vFaduxmMk0Optn21ArHgZRdXaHtqQmdDZu00lP4+tseip+F1HQ7AeE7Aj3uh7ivXg79CexZ4J2dpiZ0bccJ+W8+74H10zboqnb07rc79yb4p/k2NU9FoSsL4S76ag+Rwhad8+2mSU0GDlZ83uGniJ2JkAk7XT5onRtvxLbs0Ns8KbprhCKqMZNj7gEdCakkPkQrA6L3qhPtBLQL8zoIcT90c6I9c9aI5K896hRyUBwAnRHkbNln8p5xEdnyxmCxc/amGn80ioStsoBaikhDs0W/G6qFIkMyDu5430xGWTYNUUkb+0K4DJx5gN4KocjQng6dK2nNTCDhayk1ect3puTS1I9r3YF0n02=v8xw-----END PGP SIGNATURE-----
X
X
Xinglu Chen wrote on 26 May 16:57 +0200
[PATCH] doc: Expound on how to specify the version of a package.
(address . 48667@debbugs.gnu.org)(name . Nicolas Goaziou)(address . mail@nicolasgoaziou.fr)
7a6a9bffa80fdfaa1e14015614cb638ff8cc7441.1622040691.git.public@yoctocell.xyz
* doc/guix.texi (package Reference): Describe how packages that lack a releaseor 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(-)
Toggle diff (55 lines)diff --git a/doc/guix.texi b/doc/guix.texiindex 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
L
L
Ludovic Courtès wrote on 5 Jun 22:29 +0200
(name . Xinglu Chen)(address . public@yoctocell.xyz)
87zgw4m4xa.fsf_-_@gnu.org
Hi Xinglu,
Xinglu Chen <public@yoctocell.xyz> skribis:
Toggle quote (4 lines)> * 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.
[...]
Toggle quote (18 lines)> @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 forit: it’s the reference, whereas the text above is a guideline.
The “Version Numbers” section under “Packaging Guidelines” alreadytouches 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’.
X
X
Xinglu Chen wrote on 6 Jun 11:09 +0200
Re: [bug#48667] [PATCH] doc: Expound on how to specify the version of a package.
(name . Ludovic Courtès)(address . ludo@gnu.org)
87k0n7740t.fsf@yoctocell.xyz
On Sat, Jun 05 2021, Ludovic Courtès wrote:
Toggle quote (44 lines)> 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 italready all the information I was looking for. Since ‘hg-version’ wasjust added, I will mention it as well. :)
-----BEGIN PGP SIGNATURE-----
iQJJBAEBCAAzFiEEAVhh4yyK5+SEykIzrPUJmaL7XHkFAmC8kOIVHHB1YmxpY0B5b2N0b2NlbGwueHl6AAoJEKz1CZmi+1x5a6gP/0xysgVvTA5TMM+lO+FWAv/Ost2064XJgJRhtmay5ba/hDG1p2VvWYQk2BvwS6dnvQKPs2fG9gAEwxUOqPcCyS3pZkafnOY3hZyXAvJDppjLBfKhClvcpIDItukHpdTZW5oCxd0y61huL7j2VpPkMBoNvwso6U2pvW82LvK7/j73N5/KLnVxtHpmCUBXHV4qZHaE4FssjpMru08u6zSmQTdo/ZSUxo2PQJ8APyr/t4cAdfJbKN3GHyjN70ay/TixzWbglCUPTvAMuijHU0Rh937Iq0yvdkxLm+1lv4yaC3OiAnPrPfZXfOqw/fsY6zhDxpHHPPQwvgp4xLpbQ2gZsw22X8m8ZuIZ1gvCdrQL7BmtS0vHFOVjy4X8FsPiz3CxDC5TU4kkRu+L8sYQRjf/vmVqnUMXA3pxw9F+AUVM077v5o7l+UD6UsfnMnyB5k6E+PARpz/DefVeJURmQVNCUIWVZuR+MGx0BdipaPe9NVWfmnQhO9FiAjHZ/v9gq8hEHa5Z6RnfNnbP2C6AWxgJd3h8PndPKqnsxk/scI2GHzBpYVqsvPH37shwuzlvNhR6SxcL/OgZT9WL5SkVd5z7MjQPs9ID41cmZgaBtT1mv1RFsjS0OGp0+wvFHW5W+pR1qdDJ6+u8IPyYUeoFXUQ0QGlrrlk1tqH78sLr+Jt1cOW2=oX+S-----END PGP SIGNATURE-----
X
X
Xinglu Chen wrote on 6 Jun 11:19 +0200
[PATCH] doc: Add reference for ‘git-ver
(address . 48667@debbugs.gnu.org)(name . Ludovic Courtès)(address . ludo@gnu.org)
539a1a894dbbe25d5370b7bfb11006f736cbc875.1622971088.git.public@yoctocell.xyz
* 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(-)
Toggle diff (66 lines)diff --git a/doc/contributing.texi b/doc/contributing.texiindex 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.texiindex 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
M
M
Maxime Devos wrote on 6 Jun 11:48 +0200
(name . Ludovic Courtès)(address . ludo@gnu.org)
990f6b1bf7bcd9e78f212b8615e0201c48a81b2f.camel@telenet.be
Xinglu Chen schreef op zo 06-06-2021 om 11:19 [+0200]:
Toggle quote (14 lines)> +@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.
-----BEGIN PGP SIGNATURE-----
iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYLyZ6RccbWF4aW1lZGV2b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7neLAP9Z7/9lcMLFTeSV6pBOIRXPQjXgQFJR/LLJyl6PjBxonwEAyAdYFrwPTNtBRIiKBgWXx/no6O54G8gQq9aKiW71VQ4==AAII-----END PGP SIGNATURE-----

X
X
Xinglu Chen wrote on 6 Jun 12:33 +0200
(name . Ludovic Courtès)(address . ludo@gnu.org)
875yyr7052.fsf@yoctocell.xyz
On Sun, Jun 06 2021, Maxime Devos wrote:
Toggle quote (22 lines)> 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.
-----BEGIN PGP SIGNATURE-----
iQJJBAEBCAAzFiEEAVhh4yyK5+SEykIzrPUJmaL7XHkFAmC8pIkVHHB1YmxpY0B5b2N0b2NlbGwueHl6AAoJEKz1CZmi+1x5yIMQAKsGahMzkw20IgkLS6Ysr8rbYz6P+3bRLHEGUCao7cx2KDZCAaaNRldVqhqTEkBZ0+AGvPGwQsIRtKKBcCQAFt/0MoKZNNN/1Vo5XDM/WgC7RhiG/uvTJDNXl1jbA6Esvi5OXEAXuW7kQ36VFwoLj5VpWSVjS0TvR+PNmEsgXxE9t2MO2zUt/TlEzsmfuavCnapeNkF+DH+Pylc+Ycd6tvFI5yC0kaWrT69kpZHYzzTMJGfcYxS33E0TtacDxfhjpAIkhz3k9A3cWovEsUO4BZhQtcXeQGayB1Oa4/LJNH0OtIEk3KzjeyDJ/cCtGI6Svb43QJPm0eDzSWU3rUSkwb1cR6bK49tcmSCvfMQnSvwNIGMekViUxf1PgYXEZ7o4wqExFRgFCCyNKMZ2rU9YdyfKMFqvlCba+PE1deRlkgDpnQVJdMJjNljs/95CGYCLZjfFW6JBEVBg+zwaTlSsJdZhK3caN/aYbbB2i0lzk0eed6//CxiZhLSDgkADOL8RjPaps3VyoENgrenmQ/LitLx05yuUSWdLP20ktUF62KigOkeRduJ08Ikgi2K1SrBq8OhuDdtihApgp5YMvRwcTo2CcuML7mh41xZOFbIAXynqiIWZ9cUe65kur2Yp84Yx/sMHNLk+lnpFhuzOE8yzggVeQdEpwo3a23UAKc33pcOh=GR/1-----END PGP SIGNATURE-----
X
X
Xinglu Chen wrote on 6 Jun 12:37 +0200
[PATCH v2] doc: Add refernece for ‘git-version ’ and ‘hg-version’.
(address . 48667@debbugs.gnu.org)
7354a84803acc09bb64feb8b94519b9e5093d050.1622975743.git.public@yoctocell.xyz
* 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(-)
Toggle diff (66 lines)diff --git a/doc/contributing.texi b/doc/contributing.texiindex 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.texiindex 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
L
L
Ludovic Courtès wrote on 6 Jun 14:36 +0200
Re: [PATCH v2] doc: Add refernece for ‘git-vers ion’ and ‘hg-version’.
(name . Xinglu Chen)(address . public@yoctocell.xyz)
87czszkw4k.fsf@gnu.org
Hi,
Xinglu Chen <public@yoctocell.xyz> skribis:
Toggle quote (5 lines)> * 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’.
Closed
?