* Package naming / versioning guidelines.

svn path=/nixpkgs/trunk/; revision=18433

1 files changed, 110 insertions, 0 deletions

diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml
index 282fad66280..e55f86ae3d3 100644
--- a/doc/coding-conventions.xml
+++ b/doc/coding-conventions.xml
@@ -207,6 +207,79 @@ args.stdenv.mkDerivation (args // {
 </section>
 
 
+<section><title>Package naming</title>
+
+<para>In Nixpkgs, there are generally three different names associated with a package:
+
+<itemizedlist>
+
+  <listitem><para>The <varname>name</varname> attribute of the
+  derivation (excluding the version part).  This is what most users
+  see, in particular when using
+  <command>nix-env</command>.</para></listitem>
+
+  <listitem><para>The variable name used for the instantiated package
+  in <filename>all-packages.nix</filename>, and when passing it as a
+  dependency to other functions.  This is what Nix expression authors
+  see.  It can also be used when installing using <command>nix-env
+  -iA</command>.</para></listitem>
+
+  <listitem><para>The filename for (the directory containing) the Nix
+  expression.</para></listitem>
+
+</itemizedlist>
+
+Most of the time, these are the same.  For instance, the package
+<literal>e2fsprogs</literal> has a <varname>name</varname> attribute
+<literal>"e2fsprogs-<replaceable>version</replaceable>"</literal>, is
+bound to the variable name <varname>e2fsprogs</varname> in
+<filename>all-packages.nix</filename>, and the Nix expression is in
+<filename>pkgs/os-specific/linux/e2fsprogs/default.nix</filename>.
+However, identifiers in the Nix language don’t allow certain
+characters (e.g. dashes), so sometimes a different variable name
+should be used.  For instance, the
+<literal>module-init-tools</literal> package is bound to the
+<literal>module_init_tools</literal> variable in
+<filename>all-packages.nix</filename>.</para>
+
+<para>There are a few naming guidelines:
+
+<itemizedlist>
+
+  <listitem><para>Generally, try to stick to the upstream package
+  name.</para></listitem>
+
+  <listitem><para>Don’t use uppercase letters in the
+  <literal>name</literal> attribute — e.g.,
+  <literal>"mplayer-1.0rc2"</literal> instead of
+  <literal>"MPlayer-1.0rc2"</literal>.</para></listitem>
+
+  <listitem><para>The version part of the <literal>name</literal>
+  attribute <emphasis>must</emphasis> start with a digit (following a
+  dash) — e.g., <literal>"hello-0.3-pre-r3910"</literal> instead of
+  <literal>"hello-svn-r3910"</literal>, as the latter would be seen as
+  a package named <literal>hello-svn</literal> by
+  <command>nix-env</command>.</para></listitem>
+
+  <listitem><para>Dashes in the package name should be changed to
+  underscores in variable names, rather than to camel case — e.g.,
+  <varname>module_init_tools</varname> instead of
+  <varname>moduleInitTools</varname>.</para></listitem>
+
+  <listitem><para>If there are multiple versions of a package, this
+  should be reflected in the variable names in
+  <filename>all-packages.nix</filename>,
+  e.g. <varname>hello_0_3</varname> and <varname>hello_0_4</varname>.
+  If there is an obvious “default” version, make an attribute like
+  <literal>hello = hello_0_4;</literal>.</para></listitem>
+
+</itemizedlist>
+
+</para>
+
+</section>
+
+
 <section xml:id="sec-organisation"><title>File naming and organisation</title>
 
 <para>Names of files and directories should be in lowercase, with
@@ -215,6 +288,8 @@ dashes between words — not in camel case.  For instance, it should be
 <filename>allPackages.nix</filename> or
 <filename>AllPackages.nix</filename>.</para>
 
+<section><title>Hierachy</title>
+
 <para>Each package should be stored in its own directory somewhere in
 the <filename>pkgs/</filename> tree, i.e. in
 <filename>pkgs/<replaceable>category</replaceable>/<replaceable>subcategory</replaceable>/<replaceable>...</replaceable>/<replaceable>pkgname</replaceable></filename>.
@@ -492,4 +567,39 @@ splitting up an existing category.</para>
 
 </section>
 
+<section><title>Versioning</title>
+
+<para>Because every version of a package in Nixpkgs creates a
+potential maintenance burden, old versions of a package should not be
+kept unless there is a good reason to do so.  For instance, Nixpkgs
+contains several versions of GCC because other packages don’t build
+with the latest version of GCC.  Other examples are having both the
+latest stable and latest pre-release version of a package, or to keep
+several major releases of an application that differ significantly in
+functionality.</para>
+
+<para>If there is only one version of a package, its Nix expression
+should be named <filename>e2fsprogs/default.nix</filename>.  If there
+are multiple versions, this should be reflected in the filename,
+e.g. <filename>e2fsprogs/1.41.8.nix</filename> and
+<filename>e2fsprogs/1.41.9.nix</filename>.  The version in the
+filename should leave out unnecessary detail.  For instance, if we
+keep the latest Firefox 2.0.x and 3.5.x versions in Nixpkgs, they
+should be named <filename>firefox/2.0.nix</filename> and
+<filename>firefox/3.5.nix</filename>, respectively (which, at a given
+point, might contain versions <literal>2.0.0.20</literal> and
+<literal>3.5.4</literal>).  If a version requires many auxiliary
+files, you can use a subdirectory for each version,
+e.g. <filename>firefox/2.0/default.nix</filename> and
+<filename>firefox/3.5/default.nix</filename>.</para>
+
+<para>All versions of a package <emphasis>must</emphasis> be included
+in <filename>all-packages.nix</filename> to make sure that they
+evaluate correctly.</para>
+
+</section>
+
+</section>
+
+
 </chapter>