From f7c25bf9c2b48027bd13bb92365bebbf8fa97060 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <eelco.dolstra@logicblox.com>
Date: Wed, 2 Dec 2015 13:54:24 +0100
Subject: [PATCH] Manual: Add a warning that overrideDerivation should not be
 used

---
 doc/functions.xml | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/doc/functions.xml b/doc/functions.xml
index 39010f8ab145..e2bc751e1402 100644
--- a/doc/functions.xml
+++ b/doc/functions.xml
@@ -88,6 +88,13 @@ in ...</programlisting>
 <section xml:id="sec-pkg-overrideDerivation">
   <title>&lt;pkg&gt;.overrideDerivation</title>
 
+  <warning>
+    <para>Do not use this function in Nixpkgs. Because it breaks
+    package abstraction and doesn’t provide error checking for
+    function arguments, it is only intended for ad-hoc customisation
+    (such as in <filename>~/.nixpkgs/config.nix</filename>).</para>
+  </warning>
+
   <para>
     The function <varname>overrideDerivation</varname> is usually available for all the
     derivations in the nixpkgs expression (<varname>pkgs</varname>).