Re: Agreeing on some "rules" for packaging.
Nikita Karetnikov skribis: > I’ve just fixed a small bug [1]. Maybe we should agree to run > > make distclean && ./boostrap && ./configure && make && make check > > before pushing, or will it be too tedious? For this kind of error (unbound variable), just typing ‘make’ or C-c C-k in Geiser reports the unbound variable. Doing that before pushing is definitely advised. Sometimes that’s not enough to detect other errors (such as circular dependencies), but that’s quite unusual. > Also, I don’t like the ‘license:’ prefix. What about something like > ‘l:’? It’ll probably be even better to use ‘#:select’ when it’s > possible. Yes, I prefer #:select when possible, but otherwise either of these two prefixes is fine with me. Thanks, Ludo’.
Re: Agreeing on some "rules" for packaging.
On Sat, Sep 07, 2013 at 12:20:23PM +0400, Nikita Karetnikov wrote: > make distclean && ./boostrap && ./configure && make && make check > before pushing, or will it be too tedious? Would "make" not be enough? Usually there is a warning message when there is a problem. > Also, I don’t like the ‘license:’ prefix. What about something like > ‘l:’? It’ll probably be even better to use ‘#:select’ when it’s > possible. Personally, I would do things the other way round and always use a prefix... Then I can simply write down the license of a package without checking whether it is already selected in the module. Andreas
Re: Agreeing on some "rules" for packaging.
I’ve just fixed a small bug [1]. Maybe we should agree to run make distclean && ./boostrap && ./configure && make && make check before pushing, or will it be too tedious? Also, I don’t like the ‘license:’ prefix. What about something like ‘l:’? It’ll probably be even better to use ‘#:select’ when it’s possible. [1] http://git.savannah.gnu.org/cgit/guix.git/commit/?id=a129e0d877f125693f58457d55973d184468b461 pgppVhZC5MCZi.pgp Description: PGP signature
Re: Agreeing on some "rules" for packaging.
Andreas Enge skribis: > On Sat, Aug 31, 2013 at 11:31:08AM +0200, Ludovic Courtès wrote: >> > No, since @xref creates text starting by "See", so is only suitable for the >> > beginning of a sentence. >> In general, it is best to use '@ref' only when you need some word >> other than "see" to precede the reference. When "see" (or "See") is ok, >> '@xref' and '@pxref' are preferable. > > Well, but I would like to start my sentence with "But" and not "See", since > I am pointing the reader to something that contradicts the previous > sentence... > >> >> s/defined in @ref {Package Naming}/previously defined (@pxref{Package >> >> Naming})/ >> > This also gives strange output with an additional "see". >> previously defined (see Section 4.2 “Package Naming”) > > and I would like to write "defined in Section..." and not "previously defined > (see Section". > > These info rules should not meddle with our writing style. Sure, but the topic of making cross-references that work across media isn’t trivial, which is why Texinfo has several commands with clear rules. > The result is what I wanted to achieve in the pdf, and I think it > looks acceptable in info. Well, by definition, constructs like these look bad in Info. However, perhaps it’s kinda OK with Emacs’ Info reader, which uses hyperlinks. Nevertheless, I’ve never found it such a hindrance to follow the Texinfo rules. >> > Okay. I suppose this also means that the period at the end of a sentence >> > is not allowed to fall at the end of an input line? >> No, that’s not necessary, fortunately. > > So texinfo interprets periods at the end of a line as ends of sentences? Presumably, but I don’t know the details. Thanks, Ludo’.
Re: Agreeing on some "rules" for packaging.
On Sat, Aug 31, 2013 at 11:31:08AM +0200, Ludovic Courtès wrote: > > No, since @xref creates text starting by "See", so is only suitable for the > > beginning of a sentence. > In general, it is best to use '@ref' only when you need some word > other than "see" to precede the reference. When "see" (or "See") is ok, > '@xref' and '@pxref' are preferable. Well, but I would like to start my sentence with "But" and not "See", since I am pointing the reader to something that contradicts the previous sentence... > >> s/defined in @ref {Package Naming}/previously defined (@pxref{Package > >> Naming})/ > > This also gives strange output with an additional "see". > previously defined (see Section 4.2 “Package Naming”) and I would like to write "defined in Section..." and not "previously defined (see Section". These info rules should not meddle with our writing style. The result is what I wanted to achieve in the pdf, and I think it looks acceptable in info. > > Okay. I suppose this also means that the period at the end of a sentence > > is not allowed to fall at the end of an input line? > No, that’s not necessary, fortunately. So texinfo interprets periods at the end of a line as ends of sentences? And instead of "a Scheme interpreter, e.g. Guile" one has to write "a Scheme interpreter, e.g. Guile"? Andreas
Re: Agreeing on some "rules" for packaging.
Andreas Enge skribis: > On Thu, Aug 29, 2013 at 12:42:31AM +0200, Ludovic Courtès wrote: [...] >> I would perhaps move “Python Modules” into a “Specific Packages” >> subsection (or something like that), where we might eventually have >> “Perl Packages” as well. WDYT? > > Maybe once we have Perl Packages. I do not want to create too many sublevels. > Or we just create a separate section Perl Packages, depending on whether we > write essentially the same thing or not. OK, makes sense. >> s/But see @ref{Python Modules}/@xref{Python Modules},/ > > No, since @xref creates text starting by "See", so is only suitable for the > beginning of a sentence. What I’m suggesting here is precisely to start the sentence with @xref, as recommended (info "(texinfo) @ref"): The '@ref' command can tempt writers to express themselves in a manner that is suitable for a printed manual but looks awkward in the Info format. [...] In general, it is best to use '@ref' only when you need some word other than "see" to precede the reference. When "see" (or "See") is ok, '@xref' and '@pxref' are preferable. >> s/defined in @ref {Package Naming}/previously defined (@pxref{Package >> Naming})/ > > This also gives strange output with an additional "see". It yields something like: previously defined (see Section 4.2 “Package Naming”) How strange is that? :-) >> Also, please leave two spaces after an end-of-sentence period. > > Okay. I suppose this also means that the period at the end of a sentence > is not allowed to fall at the end of an input line? No, that’s not necessary, fortunately. > Since there have not been any objections on the content of the guidelines, > maybe you could push Python 3 following this rule, Cyril? I am curious > whether all our packages will survive the switch to Python 3... Well let’s pull the trigger and see what happens. :-) Thanks, Ludo’.
Re: Agreeing on some "rules" for packaging.
On Thu, Aug 29, 2013 at 12:42:31AM +0200, Ludovic Courtès wrote: > Looks like it already went in. :-) Yes, that was a random push, sorry! But the good thing in a vcs is that one can always modify and go back. > I would perhaps move “Python Modules” into a “Specific Packages” > subsection (or something like that), where we might eventually have > “Perl Packages” as well. WDYT? Maybe once we have Perl Packages. I do not want to create too many sublevels. Or we just create a separate section Perl Packages, depending on whether we write essentially the same thing or not. > > +A package has actually two names associated to it: > s/to it/with it/ Ok. > s/package manager/commands such as @command{guix package} and @command{guix > build}/ "package management commands such as ... > > +Both are usually the same and correspond to the lowercase conversion of the > > +project name chosen by upstream. For instance, the GNUnet project is > > packaged > s/by upstream/upstream/ Ok. > s/But see @ref{Python Modules}/@xref{Python Modules},/ No, since @xref creates text starting by "See", so is only suitable for the beginning of a sentence. (But the info rendering is different from the pdf, with which I am working mainly.) > s/defined in @ref {Package Naming}/previously defined (@pxref{Package > Naming})/ This also gives strange output with an additional "see". > Add linebreaks around @example, possibly with @noindent before the > lonely lines. Okay for the line break (which does not change anything in pdf). > Add linebreak before “Some modules”. Okay. > Also, please leave two spaces after an end-of-sentence period. Okay. I suppose this also means that the period at the end of a sentence is not allowed to fall at the end of an input line? So "The weather is nice. It is raining." needs to become, for instance: "The weather is nice. It is raining."? Since there have not been any objections on the content of the guidelines, maybe you could push Python 3 following this rule, Cyril? I am curious whether all our packages will survive the switch to Python 3... Andreas
Re: Agreeing on some "rules" for packaging.
While we’re at discussing rules: commit e1c5a83 adds a “Coding Style” section in ‘HACKING’, with the ideas that came to mind. Let me know what you think. Ludo’.
Re: Agreeing on some "rules" for packaging.
Nikita Karetnikov skribis: >> Yes, that change in the GCS is recent, and I haven’t completely changed >> my habits. > >> IMO the rule should be: use Unicode quotation marks wherever possible >> (almost everywhere), use what Texinfo prescribes in Texinfo (that is, >> like `this' and ``that''), and use what the GCS says elsewhere. > >> I tend to use ASCII quotation marks in source files; the main reason for >> that is that typopunct-mode in Scheme files would be annoying (if you >> know of other ways do use Unicode quotation marks in Emacs, lemme know.) > >> Thoughts? > > OK, but the above doesn’t answer my question. Which quotation marks > should be used in source files: `' or ''? Unicode if that’s convenient, or 'this'. (Although again, I tend to do `this'...) > And what about commit messages? Ditto. Ludo’.
Re: Agreeing on some "rules" for packaging.
> Yes, that change in the GCS is recent, and I haven’t completely changed > my habits. > IMO the rule should be: use Unicode quotation marks wherever possible > (almost everywhere), use what Texinfo prescribes in Texinfo (that is, > like `this' and ``that''), and use what the GCS says elsewhere. > I tend to use ASCII quotation marks in source files; the main reason for > that is that typopunct-mode in Scheme files would be annoying (if you > know of other ways do use Unicode quotation marks in Emacs, lemme know.) > Thoughts? OK, but the above doesn’t answer my question. Which quotation marks should be used in source files: `' or ''? And what about commit messages? pgpguTseZ4SHi.pgp Description: PGP signature
Re: Agreeing on some "rules" for packaging.
Nikita Karetnikov skribis: > While we are at it, we could agree on quotation marks. I know that it > sounds like bikeshedding… However, it doesn’t look right when some > people use `' and others use ''. > > “Although GNU programs traditionally used 0x60 (‘`’) for opening and 0x27 > (‘'’) for closing quotes, nowadays quotes ‘`like this'’ are typically > rendered asymmetrically, so quoting ‘"like this"’ or ‘'like this'’ > typically looks better.” [1] > > I’d prefer '' but will use `' if we agree on that. > > [1] https://gnu.org/prep/standards/standards.html#Quote-Characters Yes, that change in the GCS is recent, and I haven’t completely changed my habits. IMO the rule should be: use Unicode quotation marks wherever possible (almost everywhere), use what Texinfo prescribes in Texinfo (that is, like `this' and ``that''), and use what the GCS says elsewhere. I tend to use ASCII quotation marks in source files; the main reason for that is that typopunct-mode in Scheme files would be annoying (if you know of other ways do use Unicode quotation marks in Emacs, lemme know.) Thoughts? Ludo’.
Re: Agreeing on some "rules" for packaging.
While we are at it, we could agree on quotation marks. I know that it sounds like bikeshedding… However, it doesn’t look right when some people use `' and others use ''. “Although GNU programs traditionally used 0x60 (‘`’) for opening and 0x27 (‘'’) for closing quotes, nowadays quotes ‘`like this'’ are typically rendered asymmetrically, so quoting ‘"like this"’ or ‘'like this'’ typically looks better.” [1] I’d prefer '' but will use `' if we agree on that. [1] https://gnu.org/prep/standards/standards.html#Quote-Characters pgp_rHzlL15fs.pgp Description: PGP signature
Re: Agreeing on some "rules" for packaging.
Cyril Roelandt skribis: > On 08/29/2013 12:42 AM, Ludovic Courtès wrote: >> Also, please leave two spaces after an end-of-sentence period. > > Do you have a link to an explanation of this rule ? >From (info "(texinfo) Not Ending a Sentence"): Depending on whether a period or exclamation point or question mark is inside or at the end of a sentence, slightly less or more space is inserted after a period in a typeset manual. Since it is not always possible to determine automatically when a period ends a sentence, special commands are needed in some circumstances. Usually, Texinfo can guess how to handle periods, so you do not need to use the special commands; you just enter a period as you would if you were using a typewriter: put two spaces after the period, question mark, or exclamation mark that ends a sentence. IOW, the intent is to (1) mimic typographical rules, where an end-of-sentence space is slightly wider than (say) an after-abbreviation-period space, and (2) to guide TeX(info). Also, the ‘forward-sentence’ (M-e) command in Emacs expects that. Ludo’.
Re: Agreeing on some "rules" for packaging.
On 08/29/2013 12:42 AM, Ludovic Courtès wrote: Also, please leave two spaces after an end-of-sentence period. Do you have a link to an explanation of this rule ? Cyril.
Re: Agreeing on some "rules" for packaging.
Andreas Enge skribis: > Please find attached a patch with proposed conventions for package names, > including in the presence of packages for several version numbers > (such as python itself), and for python modules. Looks like it already went in. :-) That seems like a very good start. I agree with the proposed rules, so I just have a cosmetic comments: > diff --git a/doc/guix.texi b/doc/guix.texi > index dfffdbf..ca2871b 100644 > --- a/doc/guix.texi > +++ b/doc/guix.texi > @@ -1631,7 +1631,10 @@ needed is to review and apply the patch. > > > @menu > -* Software Freedom:: What may go into the > distribution. > +* Software Freedom:: What may go into the distribution. > +* Package Naming:: What's in a name? > +* Version Numbers:: When the name is not enough. > +* Python Modules:: Taming the snake. > @end menu I would perhaps move “Python Modules” into a “Specific Packages” subsection (or something like that), where we might eventually have “Perl Packages” as well. WDYT? > +@node Package Naming > +@subsection Package Naming > + > +A package has actually two names associated to it: s/to it/with it/ > +First, there is the name of the @emph{Scheme variable}, the one following > +@code{define-public}. By this name, the package can be made known in the > +Scheme code, for instance as input to another package. > +Second, there is the string in the @code{name} field of a package definition. > +This name is used by the package manager. s/package manager/commands such as @command{guix package} and @command{guix build}/ > +Both are usually the same and correspond to the lowercase conversion of the > +project name chosen by upstream. For instance, the GNUnet project is packaged s/by upstream/upstream/ > +as @code{gnunet}. We do not add @code{lib} prefixes for library packages, > +unless these are already part of the official project name. > +But see @ref{Python Modules} for special rules concerning modules for s/But see @ref{Python Modules}/@xref{Python Modules},/ (info "(texinfo) @xref") > +@node Version Numbers > +@subsection Version Numbers > + > +We usually package only the latest version of a given free software > +project. But sometimes, for instance for incompatible library versions, > +two (or more) versions of the same package are needed. These require > different > +Scheme variable names. We use the name as defined in @ref {Package Naming} s/defined in @ref {Package Naming}/previously defined (@pxref{Package Naming})/ > +for the most recent version; previous versions use the same name, suffixed > +by @code{-} and the smallest prefix of the version number that may > +distinguish the two versions. > + > +The name inside the package definition is the same for all versions of a > +package and does not contain any version number. > + > +For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as > follows: > +@example > +(define-public gtk+ > + (package > + (name "gtk+") > + (version "3.9.12") > + ...)) > +(define-public gtk+-2 > + (package > + (name "gtk+") > + (version "2.24.20") > + ...)) > +@end example > +If we also wanted GTK+ 3.8.2, this would be packaged as > +@example > +(define-public gtk+-3.8 > + (package > + (name "gtk+") > + (version "3.8.2") > + ...)) > +@end example Add linebreaks around @example, possibly with @noindent before the lonely lines. > +@node Python Modules > +@subsection Python Modules > + > +We currently package Python 2 and Python 3, under the Scheme variable names > +@code{python-2} and @code{python} as explained in @ref{Version Numbers}. > +To avoid confusion and naming clashes with other programming languages, it > +seems desirable that the name of a package for a Python module contains > +the word @code{python}. > +Some modules are compatible with only one version of Python, others with > both. Add linebreak before “Some modules”. Also, please leave two spaces after an end-of-sentence period. Thanks, Ludo’.
Re: Agreeing on some "rules" for packaging.
Cyril Roelandt skribis: > On 08/28/2013 02:51 PM, Ludovic Courtès wrote: >> Cyril Roelandt skribis: [...] >>> I would also like to define a standard way to order the "#:use-module" >>> at the beginning of each file, and agree on other "cosmetic" rules. >> >> Not convinced about the ordering. ;-) >> > > Isn't there such a convention in Scheme ? Not that I know of. I generally put the (guix ...) modules first, and the (gnu ...) second, I think. IOW, the “foundational” first. >> These are good examples of the kind of rules we may want to discuss and >> adopt. > > > I'm also wondering how to name python packages. foo ? python-foo and > python3-foo ? python2-foo and python-foo ? Presumably pythonX-foo. Andreas? Ludo’.
Re: Agreeing on some "rules" for packaging.
Please find attached a patch with proposed conventions for package names, including in the presence of packages for several version numbers (such as python itself), and for python modules. Andreas >From ee85f3dbe9ec38abffd08971be27b876634392ee Mon Sep 17 00:00:00 2001 From: Andreas Enge Date: Wed, 28 Aug 2013 22:51:20 +0200 Subject: [PATCH] doc: Add package guidelines for names and numbers. * doc/guix.texi: Three new subsections. --- doc/guix.texi | 82 - 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/doc/guix.texi b/doc/guix.texi index dfffdbf..ca2871b 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1631,7 +1631,10 @@ needed is to review and apply the patch. @menu -* Software Freedom:: What may go into the distribution. +* Software Freedom:: What may go into the distribution. +* Package Naming:: What's in a name? +* Version Numbers:: When the name is not enough. +* Python Modules:: Taming the snake. @end menu @node Software Freedom @@ -1654,6 +1657,83 @@ reject non-free firmware, recommendations of non-free software, and discuss ways to deal with trademarks and patents. +@node Package Naming +@subsection Package Naming + +A package has actually two names associated to it: +First, there is the name of the @emph{Scheme variable}, the one following +@code{define-public}. By this name, the package can be made known in the +Scheme code, for instance as input to another package. +Second, there is the string in the @code{name} field of a package definition. +This name is used by the package manager. + +Both are usually the same and correspond to the lowercase conversion of the +project name chosen by upstream. For instance, the GNUnet project is packaged +as @code{gnunet}. We do not add @code{lib} prefixes for library packages, +unless these are already part of the official project name. +But see @ref{Python Modules} for special rules concerning modules for +the Python language. + + +@node Version Numbers +@subsection Version Numbers + +We usually package only the latest version of a given free software +project. But sometimes, for instance for incompatible library versions, +two (or more) versions of the same package are needed. These require different +Scheme variable names. We use the name as defined in @ref {Package Naming} +for the most recent version; previous versions use the same name, suffixed +by @code{-} and the smallest prefix of the version number that may +distinguish the two versions. + +The name inside the package definition is the same for all versions of a +package and does not contain any version number. + +For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows: +@example +(define-public gtk+ + (package + (name "gtk+") + (version "3.9.12") + ...)) +(define-public gtk+-2 + (package + (name "gtk+") + (version "2.24.20") + ...)) +@end example +If we also wanted GTK+ 3.8.2, this would be packaged as +@example +(define-public gtk+-3.8 + (package + (name "gtk+") + (version "3.8.2") + ...)) +@end example + + +@node Python Modules +@subsection Python Modules + +We currently package Python 2 and Python 3, under the Scheme variable names +@code{python-2} and @code{python} as explained in @ref{Version Numbers}. +To avoid confusion and naming clashes with other programming languages, it +seems desirable that the name of a package for a Python module contains +the word @code{python}. +Some modules are compatible with only one version of Python, others with both. +If the package Foo compiles only with Python 3, we name it +@code{python-foo}; if it compiles only with Python 2, we name it +@code{python2-foo}. If it is compatible with both versions, we create two +packages with the corresponding names. + +If a project already contains the word @code{python}, we drop this; +for instance, the module python-dateutil is packaged under the names +@code{python-dateutil} and @code{python2-dateutil}. + + + + + @node Bootstrapping @section Bootstrapping -- 1.7.10.4
Re: Agreeing on some "rules" for packaging.
On 08/28/2013 02:51 PM, Ludovic Courtès wrote: Cyril Roelandt skribis: At the GHM, a Fedora hacker (whose name I forgot) suggested that it might be time for us to write down some "rules" as to how packaging should be done. Sounds like a good idea. In general, when working in a group, I think it’s better to discuss what our expectations are, and write as much of it down, to avoid any misunderstandings or frustration. So yes, let’s do it. For instance, Andreas suggested that patches should only be used if we think they might be applied upstream, thus keeping the patches/ directory as small as possible; Agreed. Also, patches should start with a comment saying what they do, and possibly what their upstream status is (submitted, will never be submitted because it’s Guix-specific, etc.); perhaps the format of that comment could even be formalized. modifications specific to Guix should be written in Scheme. Sometimes that may be hard or inconvenient though, so I would not set that in stone. Yes, I wrote a patch that just added "#if 0 ... #endif" around a test, and that'd be harder to do in Scheme. I would also like to define a standard way to order the "#:use-module" at the beginning of each file, and agree on other "cosmetic" rules. Not convinced about the ordering. ;-) Isn't there such a convention in Scheme ? I'm often confused when looking at the beginning of a Scheme file. NetBSD has such rules for its includes (http://cvsweb.netbsd.org/bsdweb.cgi/src/share/misc/style?rev=HEAD&content-type=text/x-cvsweb-markup). What do you think ? These are good examples of the kind of rules we may want to discuss and adopt. I'm also wondering how to name python packages. foo ? python-foo and python3-foo ? python2-foo and python-foo ? Cyril.
Re: Agreeing on some "rules" for packaging.
Cyril Roelandt skribis: > At the GHM, a Fedora hacker (whose name I forgot) suggested that it > might be time for us to write down some "rules" as to how packaging > should be done. Sounds like a good idea. In general, when working in a group, I think it’s better to discuss what our expectations are, and write as much of it down, to avoid any misunderstandings or frustration. So yes, let’s do it. > For instance, Andreas suggested that patches should only be used if we > think they might be applied upstream, thus keeping the patches/ > directory as small as possible; Agreed. Also, patches should start with a comment saying what they do, and possibly what their upstream status is (submitted, will never be submitted because it’s Guix-specific, etc.); perhaps the format of that comment could even be formalized. > modifications specific to Guix should be written in Scheme. Sometimes that may be hard or inconvenient though, so I would not set that in stone. > I would also like to define a standard way to order the "#:use-module" > at the beginning of each file, and agree on other "cosmetic" rules. Not convinced about the ordering. ;-) > What do you think ? These are good examples of the kind of rules we may want to discuss and adopt. What about discussing them as patches for the “Packaging Guidelines” section of the manual, for example? (With one thread per suggestion.) Thanks! Ludo’.
Re: Agreeing on some "rules" for packaging.
Am Dienstag, 27. August 2013 schrieb Cyril Roelandt: > At the GHM, a Fedora hacker (whose name I forgot) suggested that it > might be time for us to write down some "rules" as to how packaging > should be done. It was Patrice Dumas. I agree and volunteer to propose such a document with good packaging practices. I would also like to include a page on python with a naming scheme suggestion. Would you mind holding back on python3 for so long? At least the python part should be ready by tomorrow evening. Andreas
Re: Agreeing on some "rules" for packaging.
> At the GHM, a Fedora hacker (whose name I forgot) suggested that it > might be time for us to write down some "rules" as to how packaging > should be done. Do they have such rules? > For instance, Andreas suggested that patches should only be used if we > think they might be applied upstream, thus keeping the patches/ > directory as small as possible; modifications specific to Guix should > be written in Scheme. I agree. > I would also like to define a standard way to order the "#:use-module" > at the beginning of each file, and agree on other "cosmetic" rules. I don’t think that the order is very important. Sometimes I order them alphabetically or based on the use of the functions, or group the related ones. Would you like to propose a similar set of rules for the DSL itself? pgpIr1ehlaGCh.pgp Description: PGP signature
Agreeing on some "rules" for packaging.
Hey! At the GHM, a Fedora hacker (whose name I forgot) suggested that it might be time for us to write down some "rules" as to how packaging should be done. For instance, Andreas suggested that patches should only be used if we think they might be applied upstream, thus keeping the patches/ directory as small as possible; modifications specific to Guix should be written in Scheme. I would also like to define a standard way to order the "#:use-module" at the beginning of each file, and agree on other "cosmetic" rules. What do you think ? Cyril.