Improve .md file format
* Fix typo, indentation, links, `code` font, etc.
* Minor rephrasing and ordering changes.
Change-Id: I0895fc275e5129e863685d113fca0cdf660e8923
diff --git a/src/main/resources/Documentation/about.md b/src/main/resources/Documentation/about.md
index 882249e..3a3e5cd 100644
--- a/src/main/resources/Documentation/about.md
+++ b/src/main/resources/Documentation/about.md
@@ -6,14 +6,16 @@
need *owner's* review and approval before submission,
with some exceptions.
-**OWNERS** files syntax is described in [syntax.md](syntax.md).
-Projects with **OWNERS** file should be configured with
-Prolog `submit_rule` or `submit_filter`, see [config.md](config.md).
+* Syntax and some examples of **OWNERS** files are described in [syntax.md](syntax.md).
-A **[FIND OWNERS]** action button is added to the Gerrit revision screen.
-The button pops up a window that contains
-* owners of changed files for users to select to add to the reviewers list, and
-* changed files without required *owner* code review vote.
+* Configuration examples of this plugin are included in [config.md](config.md).
+ Prolog `submit_rule` or `submit_filter` are used to enforce
+ *owner's* review and approval for projects with **OWNERS** files.
-A REST API is added to get owners information of a change.
-The API is described in [rest-api.md](rest-api.md).
+* A **[FIND OWNERS]** action button is added to the Gerrit revision screen.
+ The button pops up a window that contains
+ * owners of changed files for users to select to add to the reviewers list, and
+ * changed files without required *owner* code review vote.
+
+* A REST API is added to get owners information of a change.
+ The API is described in [rest-api.md](rest-api.md).
diff --git a/src/main/resources/Documentation/config.md b/src/main/resources/Documentation/config.md
index 838234b..4577f59 100644
--- a/src/main/resources/Documentation/config.md
+++ b/src/main/resources/Documentation/config.md
@@ -6,7 +6,7 @@
## Example from AOSP
-The **find-owners** plugin is used in Android Open Source Project (AOSP).
+The `find-owners` plugin is used in Android Open Source Project (AOSP).
Here is [one AOSP change](https://android-review.googlesource.com/c/platform/build/+/734949)
that modified multiple OWNERS files.
If you sign in to the AOSP Gerrit server,
@@ -16,58 +16,52 @@
The AOSP Gerrit server and projects are configured with the
following steps:
-1. Enable the plugin in Gerrit configuration file **gerrit.config**:
-
- ```text
+1. Enable the plugin in Gerrit configuration file `gerrit.config`:
+ ```bash
[plugin "find-owners"]
enable = true
maxCacheAge = 30
maxCacheSize = 2000
alwaysShowButton = true
```
+ * **enable = true** enables the plugin for all projects.
+ * **maxCacheAge** is the number of seconds owners info will stay in
+ a cache before being refreshed. This reduces repeated access to the same
+ OWNERS files in a repository. If it is set to 0 (default), there will
+ be no cache.
+ * **maxCacheSize** limits the number of owners info stored in the
+ cache to reduce memory footprint.
+ * **alwaysShowButton** parameter is useful for older Gerrit UI.
+ Current Gerrit UI always displays the `[FIND OWNERS]` button.
- * **maxCacheAge** is the number of seconds owners info will stay in
- a cache before refreshed. This reduces repeated access to the same
- OWNERS files in a repository. If it is set to 0 (default), there will
- be no cache.
- * **maxCacheSize** limits the number of owners info stored in the
- cache to reduce memory footprint.
- * **alwaysShowButton** parameter is useful for older Gerrit UI.
- Current Gerrit UI always displays the `[FIND OWNERS]` button.
-
-2. Enable the upload validator in **project.config** of
- the **All-Projects** project, in the **refs/meta/config** branch:
-
- ```text
+1. Enable the upload validator in `project.config` of
+ the `All-Projects` project, in the `refs/meta/config` branch:
+ ```bash
[plugin "find-owners"]
rejectErrorInOwners = true
```
+ * The upload validator checks basic syntax of uploaded OWNERS files.
+ It also checks if all email addresses used in OWNERS files
+ belong to active Gerrit accounts.
+ * All other Gerrit projects inherit from `All-Projects`,
+ so they have the same enabled upload validator.
- * The upload validator checks basic syntax of uploaded OWNERS files.
- * It also checks if all email addresses used in OWNERS files
- belong to active Gerrit accounts.
- * All other Gerrit projects inherit from **All-Projects**,
- so they have the same enabled upload validator.
-
-2. Optionally redefine **OWNERS** file name in **project.config** of
- some projects, in the **refs/meta/config** branch:
-
- ```text
+1. Optionally redefine **OWNERS** file name in `project.config` of
+ some projects, in the `refs/meta/config` branch:
+ ```bash
[plugin "find-owners"]
ownersFileName = OWNERS.android
```
+ * The AOSP `platform/external/v8` project keeps a copy of upstream
+ source from https://github.com/v8/v8.
+ * The v8 upstream source already has its `OWNERS` files
+ that do not work with AOSP Gerrit, because the Email addresses
+ in those files are not all active developers for AOSP.
+ So we need to use different *owners* files,
+ with the `OWNERS.android` file name.
- * The AOSP **platform/external/v8** project keeps a copy of upstream
- source from https://github.com/v8/v8.
- * The v8 upstream source already has its **OWNERS** files
- that do not work with AOSP Gerrit, because the Email addresses
- in those files are not all active developers for AOSP.
- So we need to use different *owners* files,
- with the **OWNERS.android** file name.
-
-4. Call the submit filters in **rules.pl** of **All-Projects**,
- in the **refs/meta/config** branch:
-
+1. Call the submit filters in `rules.pl` of `All-Projects`,
+ in the `refs/meta/config` branch:
```prolog
% Special projects, branches, user accounts can opt out owners review.
% To disable all find_owners rules, add opt_out_find_owners :- true.
@@ -116,16 +110,17 @@
change_find_owners_labels(T, R).
```
-
- * With the predefined Gerrit Prolog rules, any project, branch, or
- user can be matched and added to the **opt_out_find_owners**
- or **opt_in_find_owners** rules.
- * If the **submit_filter** output contains
- **label('Owner-Review-Vote', need(_))**,
- the Gerrit change cannot be submitted.
- * For a simpler configuration without opt-out projects,
- just call **find_owners:submit_filter**
- and **change_find_owners_labels**.
+ * With [predefined Gerrit Prolog Facts](
+ https://gerrit-review.googlesource.com/Documentation/prolog-change-facts.html),
+ any project, branch, or user can be matched
+ and added to the `opt_out_find_owners`
+ or `opt_in_find_owners` rules.
+ * If the `submit_filter` output contains
+ `label('Owner-Review-Vote', need(_))`,
+ the Gerrit change cannot be submitted.
+ * For a simpler configuration without opt-out projects,
+ just call `find_owners:submit_filter`
+ and `change_find_owners_labels`.
## The **`submit_rule`** and **`submit_filter`**
@@ -135,8 +130,8 @@
predicates for Gerrit projects.
If a Gerrit project wants to enforce this *owner-approval* policy,
-it can add a `submit_rule` to the [`rules.pl`
-file](https://gerrit-review.googlesource.com/Documentation/config-project-config.html#file-rules_pl)
+it can add a `submit_rule` to the [`rules.pl` file](
+https://gerrit-review.googlesource.com/Documentation/config-project-config.html#file-rules_pl)
in `refs/meta/config` like this:
```prolog
@@ -178,31 +173,40 @@
When `label('Owner-Approved', may(_))` is added to the submit rule output,
Gerrit displays a grey 'Owner-Approved' label. To avoid confusion,
this `may(_)` state label could be removed by the `submit_filter` of
-the root level `All-Projects`. Special automerge processes could
-create changes that do not need either Code-Review vote or owner approval.
-Such special conditions can also be handled in the `submit_filter`
-of `All-Projects`.
+the root level `All-Projects`.
+
+## Exempt from owner approval
A change can be declared as exempt from owner approval in the submit message,
with a special keyword `Exempt-From-Owner-Approval:` followed by some
explanation.
-## Default minimal owner vote level
+As shown in the AOSP example, special Prolog rules like `opt_out_find_owners`
+can be used to skip `find_owners:submit_filter` for any project, branch, or user.
+For example, special automerge processes could create changes
+that do not need either Code-Review vote or owner approval.
+
+## Default minimal owner Code-Review level
When `find_owners:submit_rule(S)` or `find_owners:submit_filter(In,Out)`
are applied, the default requirement is **+1** Code-Review
vote from at least one owner of every changed file.
+To change this default level, define the plugin `minOwnerVoteLevel` parameter.
## Default OWNERS file name
This plugin finds owners in default OWNERS files.
If a project has already used OWNERS files for other purpose,
-the "ownersFileName" parameter can be used to change the default.
+the `ownersFileName` parameter can be used to change the default.
+
+If ownersFileName is defined to something other than `OWNERS`,
+the project should have such a specified file at the root directory.
+Otherwise it would be considered a configuration or Gerrit server error.
## Validate OWNERS files before upload
To check syntax of OWNERS files before they are uploaded,
-set the following variable in project.config files.
+set the following variable in `project.config` files.
```bash
[plugin "find-owners"]
@@ -218,38 +222,32 @@
submit_filter(In, Out) :- find_owners:submit_filter(In, Out).
```
-All projects will need at least +1 vote from an owner of every changed files.
+All projects will need at least +1 Code-Review vote from an owner of every changed files.
## Example 1, call `submit_rule/2`
-Add the following to `rules.pl` of project P,
-to change the default and require **+2** owner review votes.
+To enabled owner approval requirement only for a project,
+add the following to its `rules.pl`.
+This example also changes the default and require **+2** owner Code-Review votes.
```prolog
submit_rule(S) :- find_owners:submit_rule(S, 2).
```
-All patches to project P will need at least +2 vote from
-an owner of every changed files.
-
-
## Example 2, call `submit_filter/3`
-Add the following to `rules.pl` of project P,
-to change the default and require **+2** owner review votes.
+To enabled owner approval requirement only for a project and its child projects,
+add the following to `rules.pl`.
+This example explicitly define the required owner Code-Review vote level to 1.
```prolog
-submit_filter(In, Out) :- find_owners:submit_filter(In, Out, 2).
+submit_filter(In, Out) :- find_owners:submit_filter(In, Out, 1).
```
-
-All child projects of project P will need at least +2 vote from
-an owner of every changed files.
-
## Example 3, define `minOwnerVoteLevel`
Add the following to global `gerrit.config`
or a project's `project.config` file,
-to change the default and require **+2** owner review votes.
+to change the default and require **+2** owner Code-Review votes.
```bash
[plugin "find-owners"]
@@ -260,8 +258,8 @@
If a change does not need *owner approval*, the *optional* greyed out
`Owner-Approved` label might cause some confusion.
-To remove that label, we can add the following to `rules.pl` of
-the root `All-Projects` project.
+To remove that label, we can call `remove_may_label` at the end of all
+`find_owners` submit filters, in `rules.pl` of the `All-Projects` project.
```prolog
submit_filter(In, Out) :-
@@ -277,7 +275,7 @@
```prolog
submit_filter(In, Out) :-
- is_exempt_from_owner_approval(), % define-your-own-rule
+ opt_out_find_owners, % define-your-own-rule
find_owners:remove_need_label(In, Out).
```
@@ -302,7 +300,3 @@
[plugin "find-owners"]
ownersFileName = OWNERS.android
```
-
-If ownersFileName is defined the project should have such a specified file
-at the root directory.
-Otherwise it would be considered a configuration or Gerrit server error.
diff --git a/src/main/resources/Documentation/syntax.md b/src/main/resources/Documentation/syntax.md
index f94ef41..946b362 100644
--- a/src/main/resources/Documentation/syntax.md
+++ b/src/main/resources/Documentation/syntax.md
@@ -54,18 +54,25 @@
### Examples
```bash
- # a comment starts with # to EOL; leading spaces are ignored
-set noparent # do not inherit owners defined in parent directories
+ # A comment starts with # to EOL; leading spaces are ignored.
+ # Empty lines are ignored.
+
+set noparent # Do not inherit owners defined in parent directories.
+# By default, parent directories are searched upwardly, and all
+# found OWNERS files are included until a "set noparent" is found.
+
include P1/P2:/core/OWNERS # include file core/OWNERS of project P1/P2
-include ../base/OWNERS # include with relative path to the current directory
+include ../base/OWNERS # include <this_owner_file_dir>/../base/OWNERS
+
per-file *.c,*.cpp = x@g.com,y@g.com,z@g.com
- # x@, y@ and z@ are owners of all .c or .cpp files
+# x@, y@ and z@ are owners of all *.c or *.cpp files
per-file *.c = c@g.com
- # c@, x@, y@ and z@ are owners of all .c files
+# c@, x@, y@ and z@ are owners of all *.c files
+per-file *.xml,README:*
+# no owner for *.xml and README files
+
abc@g.com # one default owner
xyz@g.com # another default owner
- # abc@ and xyz@ are owners for all files in this directory,
- # except *.c, *.cpp, *.xml, and README files
-per-file *.xml,README:* # no owner for *.xml and README files
-
+# abc@ and xyz@ are owners for all files in this directory,
+# except *.c, *.cpp, *.xml, and README files
```
