From 8ddf48b989b66488d7bf8ef7ab1ae39ebfe621bb Mon Sep 17 00:00:00 2001
From: Michael Orlitzky <mjo@gentoo.org>
Date: Sat, 22 Nov 2014 08:44:06 -0500
Subject: [PATCH 2/2] Bug #525828: Update pkg_preinst/pkg_setup text in "Users
 and Groups".

The original text on the "Users and Groups" page strongly suggested
pkg_setup() as opposed to pkg_preinst() for user/group creation. As
mentioned on bug #217042, this is not really the case: we prefer
pkg_preinst() unless the new user/group is needed to build or install
the package. The new text reflects this.
---
 ebuild-writing/users-and-groups/text.xml | 44 ++++++++++++++++++++++++++++----
 1 file changed, 39 insertions(+), 5 deletions(-)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index 5030318..f8e453d 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -8,12 +8,46 @@
 If your ebuild requires a user or group to be added for a daemon, for example,
 this should be performed via the functions available in <c>user.eclass</c>.
 Regardless of whether you are adding a group or a user, this should be performed
-in the <c>pkg_setup</c> function: <c>pkg_setup</c> is sandbox-safe,
-is called before the compile process so a build that requires the user to exist will
-have it, and is also called for both binary and source packages. You may also
-use the <c>pkg_preinst</c> or <c>pkg_postinst</c> functions for user creation, if
-the user is not required during or before <c>src_install</c>.
+in either the <c>pkg_preinst</c> or <c>pkg_setup</c> function.
 </p>
+
+<p>
+  <c>pkg_preinst</c> is the preferred location for a few reasons. If
+  the user/group is created in <c>pkg_setup</c>,
+</p>
+
+<ul>
+  <li>
+    The user/group is added on the build host even if it is not
+    required to build the package.
+  </li>
+
+  <li>
+    The user/group is created when simply unpacking the sources of a
+    package with <c>ebuild foo.ebuild unpack</c>.
+  </li>
+
+  <li>
+    The user/group remain on the system if compilation or installation
+    fails.
+  </li>
+</ul>
+
+<p>
+  However, there is a situation where the user/group <b>must</b> be
+  created in <c>pkg_setup</c>: when it is needed during compilation or
+  installation; that is, in <c>src_compile</c> or <c>src_install</c>.
+</p>
+
+<p>
+  If the build process requires the user/group to exist, then it
+  should be created in <c>pkg_setup</c> instead of
+  <c>pkg_preinst</c>. Likewise, if <c>chown &lt;user&gt;</c> or other
+  similar commands are executed during the installation, then the user
+  must already exist at that point, and so should be created in
+  <c>pkg_setup</c>.
+</p>
+
 </body>
 
 <section>
-- 
2.0.4