Config guide: Document the possibility to validate code owner configs externally
Signed-off-by: Edwin Kempin <ekempin@google.com>
Change-Id: I28d3f6c795ed4af87db35dfa37861ae122456c3d
diff --git a/resources/Documentation/config-guide.md b/resources/Documentation/config-guide.md
index 3c9432b..d59120a 100644
--- a/resources/Documentation/config-guide.md
+++ b/resources/Documentation/config-guide.md
@@ -134,6 +134,26 @@
quickly (e.g sheriffs) or users that need to make large-scale changes across
many repositories.
+## <a id="externalValidationOfCodeOwnerConfigs">External validation of code owner config files
+
+By default, when code owner config files are modified they are
+[validated](validation.html) on push. If any issues in the modified code owner
+config files are found, the push is rejected. This is important since
+non-parsable code owner config files make submissions fail which likely blocks
+the development teams, and hence needs to be prevented.
+
+However rejecting pushes in case of invalid code owner config files is not an
+ideal workflow for everyone. Instead it may be wanted that the push always
+succeeds and that issues with modified code owner config files are then detected
+and reported by a CI bot. The CI bot would then post its findings as checks on
+the open change which prevent the change submission. To enable this the
+validation of code owner config files on push can be
+[disabled](config.html#pluginCodeOwnersEnableValidationOnCommitReceived), but
+then the host admins should setup a bot to do the validation of modified code
+owner config files externally. For this the bot could use the [Check Code Owner
+Config Files In Revision](rest-api.html#check-code-owner-config-files-in-revision)
+REST endpoint.
+
## <a id="securityPitfalls">Security pitfalls
While requiring code owner approvals is primarily considered as a code quality
diff --git a/resources/Documentation/validation.md b/resources/Documentation/validation.md
index d6160d6..b3b6405 100644
--- a/resources/Documentation/validation.md
+++ b/resources/Documentation/validation.md
@@ -20,6 +20,11 @@
etc.) are severe errors and block the submission of all changes for which the
affected configuration files are relevant.
+**NOTE:** It's possible to disable the validation of code owner config files on
+push and setup an [external
+validation](config-guide.html#externalValidationOfCodeOwnerConfigs) by a CI bot
+instead. In this case findings would be posted on the change.
+
All validations are best effort to prevent invalid configurations from
entering the repository, but not all possible issues can be prevented. Doing the
validation is useful since it prevents most issues and also gives quick feedback
