From 8c6fada372dba386c25e209a4dff440e2da5a0be Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20=C4=8Cun=C3=A1t?= <vcunat@gmail.com>
Date: Sat, 3 Jun 2017 11:24:18 +0200
Subject: [PATCH] nixpkgs manual: advise against overriding whole phases

I've seen that mistake at least a few times already, e.g.
https://github.com/NixOS/nixpkgs/pull/26209#issuecomment-305925562
It might perhaps seem counter-intuitive if one doesn't know nixpkgs well.
---
 doc/stdenv.xml | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/doc/stdenv.xml b/doc/stdenv.xml
index a2530e102ca8cf..6e7134e16a5788 100644
--- a/doc/stdenv.xml
+++ b/doc/stdenv.xml
@@ -318,7 +318,13 @@ containing some shell commands to be executed, or by redefining the
 shell function
 <varname><replaceable>name</replaceable>Phase</varname>.  The former
 is convenient to override a phase from the derivation, while the
-latter is convenient from a build script.</para>
+latter is convenient from a build script.
+
+However, typically one only wants to <emphasis>add</emphasis> some
+commands to a phase, e.g. by defining <literal>postInstall</literal>
+or <literal>preFixup</literal>, as skipping some of the default actions
+may have unexpected consequences.
+</para>
 
 
 <section xml:id="ssec-controlling-phases"><title>Controlling