Re: Agreeing on some "rules" for packaging.

[ludo@gnu.org (Ludovic Courtès)]

Andreas Enge <andreas@enge.fr> 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’.