Document that code owner approvals always apply to all files in the change
Code owners may be tempted to review only the files that they own, but
this is not recommended since their approval counts for all files in the
change (as voting is done on change level, not on file level). E.g. this
is a problem if:
* a change touches files A and B
* a user owns file A, but not file B
* the user reviews only file A and approves the change
* the OWNERS files are changed so that the user owns file B too now
* the approval that was given by the user on the change approves files A
and B now, but the user actually didn't review file B
Signed-off-by: Edwin Kempin <ekempin@google.com>
Change-Id: I98af48fccefd1035795e833c23f0ee7415492a7c
diff --git a/resources/Documentation/user-guide.md b/resources/Documentation/user-guide.md
index 70dfaeb..d4308a1 100644
--- a/resources/Documentation/user-guide.md
+++ b/resources/Documentation/user-guide.md
@@ -102,6 +102,14 @@
[ignoreSelfApproval](../../../Documentation/config-labels.html#label_ignoreSelfApproval)
enabled, code owner approvals of the patch set uploader are ignored.
+**NOTE:** Code owner approvals are always applied on the whole change / patch
+set and count for all files in the change / patch set. It is not possible to
+approve individual files only. This means code owners should always review all
+files in the change / patch set before applying their approval. E.g. it is
+discouraged to only review the owned files, since the set of owned files can
+change if `OWNERS` files in the destination branch are changed after the
+approval has been applied.
+
## <a id="codeOwnerOverride">Code owner override
Usually some privileged users, such as sheriffs, are allowed to override the
