Document that refs/meta/config is often excluded from submit requirements
We had cases where project owners misconfigured a submit requirement so
that they couldn't change the refs/meta/config branch through review
anymore:
1. The project owner adds a submit requirement without applicableIf
expression although the submit requirement is intended to apply to
code branches only.
2. After the submit requirement has been added, changes to the
refs/meta/config branch can no longer be submitted, because the new
submit requirement cannot be satisfied there (e.g. it requires a vote
from a bot that doesn't run for the refs/meta/config branch).
3. The project owner cannot add the missing applicableIf expression
because submission to the refs/meta/config branch is blocked by the
unsatisfiable submit requirement.
In this case fixing the submit requirement requires bypassing code
review and projects owners may not know how to do this or it may even
not be allowed to them.
Update the documentation for the applicableIf expression to mention
explicitly that this parameter is often used to exclude the
refs/meta/config branch from a submit requirement. Maybe this can help
preventing project owners from running into the issue described above.
Signed-off-by: Edwin Kempin <ekempin@google.com>
Change-Id: I9ab8d7a37f8602aa72a11b016e8165fd997f3ffe
Release-Notes: skip
diff --git a/Documentation/config-project-config.txt b/Documentation/config-project-config.txt
index 9fd5b1b..df4cf93 100644
--- a/Documentation/config-project-config.txt
+++ b/Documentation/config-project-config.txt
@@ -9,6 +9,7 @@
relevant in an automation scenario of the access controls.
+[[refs-meta-config]]
== The +refs/meta/config+ namespace
The namespace contains three different files that play different
diff --git a/Documentation/config-submit-requirements.txt b/Documentation/config-submit-requirements.txt
index 2686f39..8298be3 100644
--- a/Documentation/config-submit-requirements.txt
+++ b/Documentation/config-submit-requirements.txt
@@ -38,6 +38,15 @@
submit requirements for certain branch patterns. See the
link:#exempt-branch-example[exempt branch] example.
+Often submit requirements should only apply to branches that contain source
+code. In this case this parameter can be used to exclude the
+link:config-project-config.html#refs-meta-config[refs/meta/config] branch from
+a submit requirement:
+
+----
+ applicableIf = -branch:refs/meta/config
+----
+
This field is optional, and if not specified, the submit requirement is
considered applicable for all changes in the project.
