Message ID | 7a6a9bffa80fdfaa1e14015614cb638ff8cc7441.1622040691.git.public@yoctocell.xyz |
---|---|
State | Accepted |
Headers | show |
Series | [bug#48667] doc: Expound on how to specify the version of a package. | expand |
Context | Check | Description |
---|---|---|
cbaines/comparison | success | View comparision |
cbaines/git branch | success | View Git branch |
cbaines/applying patch | success | View Laminar job |
cbaines/issue | success | View issue |
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’.
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. :)
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.