Document pitfalls for private changes and discourage using them for security fixes

Signed-off-by: Edwin Kempin <ekempin@google.com>
Change-Id: I2a71b66a3f4b50aaa73b415f46de4f4296d4389b

Documentation/intro-user.txt

@@ -579,10 +579,8 @@ of cases:
   creating a private throwaway change without reviewers, you can push
   from one device, and fetch to another device.
 
-* You want to do code review on a change that has sensitive
-  aspects. By reviewing a security fix in a private change,
-  outsiders can't discover the fix before it is pushed out. Even after
-  merging the change, the review can be kept private.
+Do *not* use private changes for making security fixes (see
+link:#private-changes-pitfalls[pitfalls] below).
 
 To create a private change, you push it with the `private` option.
 
@@ -606,6 +604,26 @@ can be granted
 In that case, care should be taken to prevent the CI system from
 exposing secret details.
 
+[[private-changes-pitfalls]]
+Pitfalls
+===
+
+If private changes are used, be aware of the following pitfalls:
+
+* If a private change gets merged the corresponding commit gets visible
+  for all users that can access the target branch and the private flag
+  from the change is automatically removed. This makes private changes
+  a bad choice for security fixes, as the security fix will be
+  accessible as soon as the change was merged, but for security issues
+  you want to keep an embargo until new releases have been made
+  available.
+* If you push a non-private change on top of a private change the
+  commit of the private change gets implicitly visible through the
+  parent relationship of the follow-up change.
+* If you have a series of private changes and share one with reviewers,
+  the reviewers can also see the commits of the predecessor private
+  changes through the commit parent relationship.
+
 [[ignore]]
 == Ignoring Or Marking Changes As 'Reviewed'