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

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

[Xinglu Chen]

* 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

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

[Nicolas Goaziou]

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.

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

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

[Xinglu Chen]

[-- Attachment #1: Type: text/plain, Size: 2323 bytes --]

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!


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 861 bytes --]

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

[Xinglu Chen]

* 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

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

[Ludovic Courtès]

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?

Thanks,
Ludo’.

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

[Xinglu Chen]

[-- Attachment #1: Type: text/plain, Size: 2280 bytes --]

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

> 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 it
already all the information I was looking for.  Since ‘hg-version’ was
just added, I will mention it as well.  :)


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 861 bytes --]

[bug#48667] [PATCH] doc: Add reference for ‘git-ver

[Xinglu Chen]

* 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

[bug#48667] [PATCH] doc: Add reference for ‘git-ver

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 879 bytes --]

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.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

[bug#48667] [PATCH] doc: Add reference for ‘git-ver

[Xinglu Chen]

[-- Attachment #1: Type: text/plain, Size: 951 bytes --]

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.


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 861 bytes --]

[bug#48667] [PATCH v2] doc: Add refernece for ‘git-version’ and ‘hg-version’.

[Xinglu Chen]

* 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

bug#48667: [PATCH v2] doc: Add refernece for ‘git-version’ and ‘hg-version’.

[Ludovic Courtès]

Hi,

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