Merge changes Id88e30f2,I9133556e
* changes:
Document that changing allowedEmails may cause issues in code owner configs
Extract FAQs from setup guide to own documentation page
diff --git a/resources/Documentation/config-faqs.md b/resources/Documentation/config-faqs.md
new file mode 100644
index 0000000..3ac6230
--- /dev/null
+++ b/resources/Documentation/config-faqs.md
@@ -0,0 +1,100 @@
+# Config FAQ's
+
+* [How to update the code-owners.config file for a project](#updateCodeOwnersConfig)
+* [How to check if the code owners functionality is enabled for a project or branch](#checkIfEnabled)
+* [How to avoid issues with code owner config files](#avoidIssuesWithCodeOwnerConfigs)
+* [How to investigate issues with code owner config files](#investigateIssuesWithCodeOwnerConfigs)
+
+## <a id="updateCodeOwnersConfig">How to update the code-owners.config file for a project
+
+The project-level configuration of the `code-owners` plugin is done in the
+`code-owners.config` file that is stored in the `refs/meta/config` branch of a
+project. If it is not present, all configuration parameters are inherited from
+the parent projects or the global configuration.
+
+The `code-owners.config` file has the format of a Git config file (same as the
+`project.config` file).
+
+To update the `code-owners.config` file do (requires to be a project owner):
+
+* clone the repository
+* fetch and checkout the `refs/meta/config` branch (e.g. `git fetch origin
+ refs/meta/config && git checkout FETCH_HEAD`)
+* create or edit the `code-owners.config` file
+* commit the changes
+* push the newly created commit back to the `refs/meta/config` branch (e.g. `git
+ push origin HEAD:refs/meta/config`)
+
+## <a id="checkIfEnabled">How to check if the code owners functionality is enabled for a project or branch
+
+To check if the code owners functionality is enabled for a single branch, use
+the [Get Code Owner Branch Config](rest-api.html#get-code-owner-branch-config)
+REST endpoint and inspect the
+[disabled](rest-api.html#code-owner-branch-config-info) field in the response
+(if it is not present, the code owners functionality is enabled).
+
+To check if the code owners functionality is enabled for a project or for
+multiple branches, use the [Get Code Owner Project
+Config](rest-api.html#get-code-owner-project-config) REST endpoint and inspect
+the [status](rest-api.html#code-owners-status-info) in the response (an empty
+status means that the code owners functionality is enabled for all branches of
+the project).
+
+You can invoke the REST endpoints via `curl` from the command-line or
+alternatively open the following URLs in a browser:\
+`https://<host>/projects/<project-name>/branches/<branch-name>/code_owners.branch_config`\
+`https://<host>/projects/<project-name>/code_owners.project_config`\
+(remember to URL-encode the project-name and branch-name)
+
+## <a id="avoidIssuesWithCodeOwnerConfigs">How to avoid issues with code owner config files
+
+To avoid issues with code owner config files it's highly recommended to keep the
+[validation](validation.html) of code owner config files that is performed on
+receive commits and submit enabled, as it prevents that issues are newly
+introduced to code owner config files. Whether this validation is enabled and
+whether code owner config files with new issues are rejected is controlled by
+the following configuration parameters:
+
+* [plugin.@PLUGIN@.enableValidationOnCommitReceived](config.html#pluginCodeOwnersEnableValidationOnCommitReceived)
+* [plugin.@PLUGIN@.enableValidationOnSubmit](config.html#pluginCodeOwnersEnableValidationOnSubmit)
+* [plugin.@PLUGIN@.rejectNonResolvableCodeOwners](config.html#pluginCodeOwnersRejectNonResolvableCodeOwners)
+* [plugin.@PLUGIN@.rejectNonResolvableImports](config.html#pluginCodeOwnersRejectNonResolvableImports)
+
+Since code owner config files can also get
+[issues](validation.html#howCodeOwnerConfigsCanGetIssuesAfterSubmit) after they
+have been submitted, host administrators and project owners are also recommended
+to regularly check the existing code owner config files for issues by calling
+the [Check Code Owner Config File REST
+endpoint](rest-api.html#check-code-owner-config-files) (e.g. from a cronjob) and
+then fix the reported issues.
+
+## <a id="investigateIssuesWithCodeOwnerConfigs">How to investigate issues with code owner config files
+
+If code owners config files are not working as expected, this is either caused
+by:
+
+* issues in the code owner config files
+* a bug in the @PLUGIN@ plugin
+
+Since code owner config files are part of the source code, any issues with them
+should be investigated and fixed by the project owners and host administrators.
+To do this they can:
+
+* Check the code owner config files for issues by calling the [Check Code Owner
+ Config File REST endpoint](rest-api.html#check-code-owner-config-files)
+* Check the code ownership of a user for a certain path by calling the [Check
+ Code Owner REST endpoint](rest-api.html#check-code-owner) (requires the caller
+ to be host administrator or have the [Check Code Owner
+ capability](#checkCodeOwner)).
+
+Bugs with the @PLUGIN@ plugin should be filed as issues for the Gerrit team, but
+only after issues with the code owner config files have been excluded.
+
+Also see [above](#avoidIssuesWithCodeOwnerConfigs) how to avoid issues with code
+owner config files in the first place.
+
+---
+
+Back to [@PLUGIN@ documentation index](index.html)
+
+Part of [Gerrit Code Review](../../../Documentation/index.html)
diff --git a/resources/Documentation/config-guide.md b/resources/Documentation/config-guide.md
index 8a55a6c..f96c2bc 100644
--- a/resources/Documentation/config-guide.md
+++ b/resources/Documentation/config-guide.md
@@ -6,6 +6,8 @@
recommendations for the configuration, but doesn't cover all configuration
parameters.
+Please also check out the [config FAQs](config-faqs.html).
+
## <a id="requiredConfiguration">Required Configuration
**Before** installing/enabling the plugin, or enabling the code owners
diff --git a/resources/Documentation/setup-guide.md b/resources/Documentation/setup-guide.md
index 9a0e85f..9a6e1ac 100644
--- a/resources/Documentation/setup-guide.md
+++ b/resources/Documentation/setup-guide.md
@@ -22,16 +22,11 @@
9. [Stop using the find-owners Prolog submit rule](#stopUsingFindOwners)
10. [Add an initial code owner configuration at root level](#configureCodeOwners)
-FAQ's:
-
-* [How to update the code-owners.config file for a project](#updateCodeOwnersConfig)
-* [How to check if the code owners functionality is enabled for a project or branch](#checkIfEnabled)
-* [How to avoid issues with code owner config files](#avoidIssuesWithCodeOwnerConfigs)
-* [How to investigate issues with code owner config files](#investigateIssuesWithCodeOwnerConfigs)
-
Recommendations about further configuration parameters can be found in the
[config guide](config-guide.html).
+Please also heck out the [config FAQs](config-faqs.html).
+
### <a id="configureCodeOwnersBackend">1. Configure the code owners backend that should be used
The `code-owners` plugin supports multiple [code owner backends](backends.html)
@@ -58,8 +53,8 @@
\
To configure a backend on project-level
[codeOwners.backend](config.html#codeOwnersBackend) in the
-[code-owners.config](#updateCodeOwnersConfig) file in the `refs/meta/config`
-branch can be set (requires to be a project owner).
+[code-owners.config](config-faqs.html#updateCodeOwnersConfig) file in the
+`refs/meta/config` branch can be set (requires to be a project owner).
Example per-project configuration in `code-owners.config` that configures the
[proto](backend-proto.html) backend:
@@ -71,8 +66,8 @@
\
It's also possible to configure backends per branch by setting
[codeOwners.\<branch\>.backend](config.html#codeOwnersBranchBackend) in the
-[code-owners.config](#updateCodeOwnersConfig) file in the `refs/meta/config`
-branch (requires to be a project owner).
+[code-owners.config](config-faqs.html#updateCodeOwnersConfig) file in the
+`refs/meta/config` branch (requires to be a project owner).
Example per-branch configuration in `code-owners.config` that configures the
[proto](backend-proto.html) backend:
@@ -108,7 +103,7 @@
```
\
Alternatively you may set [codeOwners.disabled](config.html#codeOwnersDisabled)
-in the [code-owners.config](#updateCodeOwnersConfig) file in the
+in the [code-owners.config](config-faqs.html#updateCodeOwnersConfig) file in the
`refs/meta/config` branch of the `All-Projects` project to `true` (requires to
be a host admin).
@@ -122,8 +117,8 @@
Enable the code owners functionality on project-level by setting
[codeOwners.disabled](config.html#codeOwnersDisabled) in the
-[code-owners.config](#updateCodeOwnersConfig) file in the `refs/meta/config`
-branch to `false` (requires to be a project owner).
+[code-owners.config](config-faqs.html#updateCodeOwnersConfig) file in the
+`refs/meta/config` branch to `false` (requires to be a project owner).
`code-owners.config`:
```
@@ -143,15 +138,15 @@
If needed, unset
[plugin.code-owners.disabled](config.html#pluginCodeOwnersDisabled) in
`gerrit.config` and [codeOwners.disabled](config.html#codeOwnersDisabled) in the
-[code-owners.config](#updateCodeOwnersConfig) file in the `refs/meta/config`
-branch of the `All-Projects` project).
+[code-owners.config](config-faqs.html#updateCodeOwnersConfig) file in the
+`refs/meta/config` branch of the `All-Projects` project).
###### b) Disable the code owners functionality in the projects/repositories that should not use code owners
Disable the code owners functionality on project-level by setting
[codeOwners.disabled](config.html#codeOwnersDisabled) in the
-[code-owners.config](#updateCodeOwnersConfig) file in the `refs/meta/config`
-branch to `true` (requires to be a project owner).
+[code-owners.config](config-faqs.html#updateCodeOwnersConfig) file in the
+`refs/meta/config` branch to `true` (requires to be a project owner).
`code-owners.config`:
```
@@ -169,9 +164,9 @@
To opt-out branches from using code owners set
[codeOwners.disabledBranch](config.html#codeOwnersDisabledBranch) in the
-[code-owners.config](#updateCodeOwnersConfig) file in the `refs/meta/config`
-branch to a regular expression that matches the branches that should be
-opted-out (requires to be a project owner).
+[code-owners.config](config.faqs.html#updateCodeOwnersConfig) file in the
+`refs/meta/config` branch to a regular expression that matches the branches that
+should be opted-out (requires to be a project owner).
`code-owners.config`:
```
@@ -188,8 +183,8 @@
[plugin.code-owners.requiredApproval](config.html#pluginCodeOwnersRequiredApproval)
in `gerrit.config` (requires to be a host admin) or per project by setting
[codeOwners.requiredApproval](config.html#codeOwnersRequiredApproval) in the
-[code-owners.config](#updateCodeOwnersConfig) file in the `refs/meta/config`
-branch (requires to be a project owner).
+[code-owners.config](config-faqs.html#updateCodeOwnersConfig) file in the
+`refs/meta/config` branch (requires to be a project owner).
Example global configuration in `gerrit.config` that requires `Code-Review+2` as
code owner approval:
@@ -254,8 +249,8 @@
[plugin.code-owners.overrideApproval](config.html#pluginCodeOwnersOverrideApproval)
in `gerrit.config` (requires to be a host admin) or per project by setting
[codeOwners.overrideApproval](config.html#codeOwnersOverrideApproval) in the
-[code-owners.config](#updateCodeOwnersConfig) file in the `refs/meta/config`
-branch (requires to be a project owner).
+[code-owners.config](config-faqs.html#updateCodeOwnersConfig) file in the
+`refs/meta/config` branch (requires to be a project owner).
Example global configuration in `gerrit.config` that requires
`Owners-Override+1` for a code owner override:
@@ -365,96 +360,6 @@
endpoint](rest-api.html#check-code-owner-config-files) and fix the reported
issues.
-### <a id="faq">FAQ's
-
-##### <a id="updateCodeOwnersConfig">How to update the code-owners.config file for a project
-
-The project-level configuration of the `code-owners` plugin is done in the
-`code-owners.config` file that is stored in the `refs/meta/config` branch of a
-project. If it is not present, all configuration parameters are inherited from
-the parent projects or the global configuration.
-
-The `code-owners.config` file has the format of a Git config file (same as the
-`project.config` file).
-
-To update the `code-owners.config` file do (requires to be a project owner):
-
-* clone the repository
-* fetch and checkout the `refs/meta/config` branch (e.g. `git fetch origin
- refs/meta/config && git checkout FETCH_HEAD`)
-* create or edit the `code-owners.config` file
-* commit the changes
-* push the newly created commit back to the `refs/meta/config` branch (e.g. `git
- push origin HEAD:refs/meta/config`)
-
-##### <a id="checkIfEnabled">How to check if the code owners functionality is enabled for a project or branch
-
-To check if the code owners functionality is enabled for a single branch, use
-the [Get Code Owner Branch Config](rest-api.html#get-code-owner-branch-config)
-REST endpoint and inspect the
-[disabled](rest-api.html#code-owner-branch-config-info) field in the response
-(if it is not present, the code owners functionality is enabled).
-
-To check if the code owners functionality is enabled for a project or for
-multiple branches, use the [Get Code Owner Project
-Config](rest-api.html#get-code-owner-project-config) REST endpoint and inspect
-the [status](rest-api.html#code-owners-status-info) in the response (an empty
-status means that the code owners functionality is enabled for all branches of
-the project).
-
-You can invoke the REST endpoints via `curl` from the command-line or
-alternatively open the following URLs in a browser:\
-`https://<host>/projects/<project-name>/branches/<branch-name>/code_owners.branch_config`\
-`https://<host>/projects/<project-name>/code_owners.project_config`\
-(remember to URL-encode the project-name and branch-name)
-
-##### <a id="avoidIssuesWithCodeOwnerConfigs">How to avoid issues with code owner config files
-
-To avoid issues with code owner config files it's highly recommended to keep the
-[validation](validation.html) of code owner config files that is performed on
-receive commits and submit enabled, as it prevents that issues are newly
-introduced to code owner config files. Whether this validation is enabled and
-whether code owner config files with new issues are rejected is controlled by
-the following configuration parameters:
-
-* [plugin.@PLUGIN@.enableValidationOnCommitReceived](config.html#pluginCodeOwnersEnableValidationOnCommitReceived)
-* [plugin.@PLUGIN@.enableValidationOnSubmit](config.html#pluginCodeOwnersEnableValidationOnSubmit)
-* [plugin.@PLUGIN@.rejectNonResolvableCodeOwners](config.html#pluginCodeOwnersRejectNonResolvableCodeOwners)
-* [plugin.@PLUGIN@.rejectNonResolvableImports](config.html#pluginCodeOwnersRejectNonResolvableImports)
-
-Since code owner config files can also get
-[issues](validation.html#howCodeOwnerConfigsCanGetIssuesAfterSubmit) after they
-have been submitted, host administrators and project owners are also recommended
-to regularly check the existing code owner config files for issues by calling
-the [Check Code Owner Config File REST
-endpoint](rest-api.html#check-code-owner-config-files) (e.g. from a cronjob) and
-then fix the reported issues.
-
-##### <a id="investigateIssuesWithCodeOwnerConfigs">How to investigate issues with code owner config files
-
-If code owners config files are not working as expected, this is either caused
-by:
-
-* issues in the code owner config files
-* a bug in the @PLUGIN@ plugin
-
-Since code owner config files are part of the source code, any issues with them
-should be investigated and fixed by the project owners and host administrators.
-To do this they can:
-
-* Check the code owner config files for issues by calling the [Check Code Owner
- Config File REST endpoint](rest-api.html#check-code-owner-config-files)
-* Check the code ownership of a user for a certain path by calling the [Check
- Code Owner REST endpoint](rest-api.html#check-code-owner) (requires the caller
- to be host administrator or have the [Check Code Owner
- capability](#checkCodeOwner)).
-
-Bugs with the @PLUGIN@ plugin should be filed as issues for the Gerrit team, but
-only after issues with the code owner config files have been excluded.
-
-Also see [above](#avoidIssuesWithCodeOwnerConfigs) how to avoid issues with code
-owner config files in the first place.
-
---
Back to [@PLUGIN@ documentation index](index.html)
diff --git a/resources/Documentation/validation.md b/resources/Documentation/validation.md
index 756edd5..3b0dc95 100644
--- a/resources/Documentation/validation.md
+++ b/resources/Documentation/validation.md
@@ -62,8 +62,9 @@
(e.g. the [accounts.visibility](../../../Documentation/config-gerrit.html#accounts.visibility)
setting is changed, [another code owners backend is
configured](setup-guide.html#configureCodeOwnersBackend) which now uses a
- different syntax or different names for code owner config files, or the [file
- extension for code owner config file is set/changed](config.html#codeOwnersFileExtension))
+ different syntax or different names for code owner config files, the [file
+ extension for code owner config file is set/changed](config.html#codeOwnersFileExtension),
+ or the [allowed email domains are changed](config.html#pluginCodeOwnersAllowedEmailDomain))
* emails of users may change so that emails in code owner configs can no longer
be resolved
* imported code owner config files may get deleted or renamed so that import
