Merge commit '891f607d5301d6730cb1f9dcf3618bcb1ab7f10e'

1 files changed, 15 insertions, 0 deletions

diff --git a/nixpkgs/doc/contributing/coding-conventions.xml b/nixpkgs/doc/contributing/coding-conventions.xml
index e587275a6383..9005a9ebafd6 100644
--- a/nixpkgs/doc/contributing/coding-conventions.xml
+++ b/nixpkgs/doc/contributing/coding-conventions.xml
@@ -178,6 +178,21 @@ args.stdenv.mkDerivation (args // {
 </programlisting>
     </para>
    </listitem>
+   <listitem>
+    <para>
+     Arguments should be listed in the order they are used, with the
+     exception of <varname>lib</varname>, which always goes first.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     Prefer using the top-level <varname>lib</varname> over its alias
+     <literal>stdenv.lib</literal>.  <varname>lib</varname> is unrelated to
+     <varname>stdenv</varname>, and so <literal>stdenv.lib</literal> should only
+     be used as a convenience alias when developing to avoid having to modify
+     the function inputs just to test something out.
+    </para>
+   </listitem>
   </itemizedlist>
  </section>
  <section xml:id="sec-package-naming">