Message ID | 06217762b07f95d2ba2d40277d010647a926df68.1622019402.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 |
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,
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!
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.