Add warning about effective rights mask

Group permission on the file should generally be at least as broad as
any file ACLs, to avoid ineffective ACLs and/or changes each time the
state is run.

salt/states/linux_acl.py

@@ -50,6 +50,24 @@ Ensure a Linux ACL list does not exist
            - damian
            - homer
          - perms: rwx
+
+.. warning::
+
+    The effective permissions of Linux file access control lists (ACLs) are
+    governed by the "effective rights mask" (the `mask` line in the output of
+    the `getfacl` command) combined with the `perms` set by this module: any
+    permission bits (for example, r=read) present in an ACL but not in the mask
+    are ignored.  The mask is automatically recomputed when setting an ACL, so
+    normally this isn't important.  However, if the file permissions are
+    changed (with `chmod` or `file.managed`, for example), the mask will
+    generally be set based on just the group bits of the file permissions.
+
+    As a result, when using `file.managed` or similar to control file
+    permissions as well as this module, you should set your group permissions
+    to be at least as broad as any permissions in your ACL. Otherwise, the two
+    state declarations will each register changes each run, and if the `file`
+    declaration runs later, your ACL will be ineffective.
+
 """