Update documentation with the latest features.
Align documentation to the latest features in terms of matching
and Prolog rules:
- ability to define extra files matchers
- extra submit rule to include owners names and associated files
Change-Id: If3b26979d5c48024332075e5e0d18c52d93470bf
diff --git a/README.md b/README.md
index 5e5b965..d4f9e20 100644
--- a/README.md
+++ b/README.md
@@ -55,10 +55,10 @@
$ git clone https://gerrit.googlesource.com/gerrit
$ cd gerrit/plugins
$ ln -s ../../owners/owners* .
- $ cp -f owners-common/external_plugin_deps.bzl .
+ $ cp -f ../../owners/external_plugin_deps.bzl .
$ cd ..
- $ bazel build plugins/owners
- $ bazel build plugins/owners-autoassign
+ $ bazel test plugins/owners-common:test
+ $ bazel build plugins/owners plugins/owners-autoassign
```
NOTE: the owners-common folder is producing shared artifacts for the two plugins
diff --git a/config.md b/config.md
index 6478ab1..c8ba3fd 100644
--- a/config.md
+++ b/config.md
@@ -1,27 +1,45 @@
## Configuration
Owner approval is determined based on OWNERS files located in the same
-repository. They are resolved against the state present in the existing master
-branch.
+repository on the target branch of the changes uploaded for review.
-The `OWNERS` files are represented by the following YAML structure:
+The `OWNERS` file has the following YAML structure:
```yaml
inherited: true
owners:
-- user-a@example.com
-- user-b@example.com
+ - some.email@example.com
+ - User Name
+matchers:
+ - suffix: .java
+ owners:
+ [...]
+ - regex: .*/README.*
+ owners:
+ [...]
+ - partial_regex: example
+ owners:
+ [...]
+ - exact: /path/to/file.txt
+ [...]
```
-_NOTE: Be aware to double check the emails values to be correctly registered as
-Gerrit users, invalid emails are just dropped._
+_NOTE: Be aware to double check that emails and full user names correspond to
+valid registered Gerrit users. When owner user full name or e-mail cannot be
+resolved, a corresponding WARN message is logged on Gerrit error_log and the
+user entry dropped._
-This translates to inheriting owner email address from any parent OWNER files
-and to allow user-a@example.com and user-b@example.com to approve the change.
+That translates to inheriting owner email address from any parent OWNER files
+and to define 'some.email@example.com' or 'User Name' users as the mandatory
+reviewers for all changes that include modification to those files.
-The plugin analyzes the latest patch set by looking at each patch and building
-an OWNERS hierarchy. It stops once it finds an OWNERS file that has “inherited”
-set to false (by default it’s true.)
+Additional owners can be specified for files selected by other matching
+conditions (matchers section). Matching can be done by file suffix, regex
+(partial or full) and exact string comparison.
+
+The plugin analyzes the latest patch set by looking at each file directory and
+building an OWNERS hierarchy. It stops once it finds an OWNERS file that has
+“inherited” set to false (by default it’s true.)
For example, imagine the following tree:
@@ -39,12 +57,21 @@
to true combine it with the owners listed in /OWNERS.
If for each patch there is a reviewer who gave a Code-Review +2 then the plugin
-will not add any labels, otherwise it will add label('Owner-Approval', need(_)).
+will not add any labels, otherwise, it will add ```label('Code-Review from owners', need(_)).```
-## Example 1
+## Example 1 - OWNERS file without matchers and default Gerrit submit rules
-Here’s a sample rules.pl that uses this predicate to enable the submit rule if
-one of the owners has given a +2
+Given an OWNERS configuration of:
+
+```yaml
+inherited: true
+owners:
+ - John Doe
+ - Doug Smith
+```
+
+And sample rules.pl that uses this predicate to enable the submit rule if
+one of the owners has given a Code Review +2
```prolog
submit_rule(S) :-
@@ -54,21 +81,31 @@
gerrit_owners:add_owner_approval(Approvers, Ds, A),
S =.. [submit | A].
```
-Let's examine how it works:
+
+Then Gerrit would evaluate the Prolog rule as follows:
It first gets the current default on rule which gives ok() if no Code-Review -2
and at least a Code-Review +2 is being provided.
Then it accumulates in Approvers the list of users who had given Code-Review +2
-and then checks if this list contains at least one of the owners of this path.
+and then checks if this list contains either 'John Doe' or 'Doug Smith'.
-If Approvers list does not contain one of the owners then Owner-Approval need() is added thus
-making the change not submittable.
+If Approvers list does not include one of the owners, then Owner-Approval need()
+is added thus making the change not submittable.
-## Example 2
+## Example 2 - OWNERS file without matchers and no default Gerrit rules
-Here's a rule which makes submittable a change if at least one of the owners has
-given a +1 without taking into consideration any other label.
+Given an OWNERS configuration of:
+
+```yaml
+inherited: true
+owners:
+ - John Doe
+ - Doug Smith
+```
+
+And a rule which makes submittable a change if at least one of the owners has
+given a +1 without taking into consideration any other label:
```prolog
submit_rule(S) :-
@@ -78,18 +115,24 @@
S =.. [submit | A].
```
+Then Gerrit would make the change Submittable only if 'John Doe' or 'Doug Smith'
+have provided at least a Code-Review +1.
-## Example 3
+## Example 3 - OWNERS file without matchers and custom _Owner-Approves_ label
-We want to allow an administrator to specify a Code-Review +2 on a change when
-all the path owners give consent with a particular new label without requiring
-them to have +2 rights on the entire project.
+Sometimes to differentiate the _owners approval_ on a change from the code
+review on the entire project. The scenario could be for instance the sign-off of
+the project's build dependencies based on the Company roles-and-responsibilities
+matrix and governance process.
-To do that we need (1) to configure in the project a new label and give access
-to it to any registered user and then (2) re-use a small variation of the
-previous rule.
+In this case, we need to grant specific people with the _Owner-Approved_ label
+without necessarily having to give Code-Review +2 rights on the entire project.
-(1) Let's define in the project general, edit config a new label with values
+Amend the project.config as shown in (1) and add a new label; then give
+permissions to any registered user. Finally, define a small variant of the
+Prolog rules as shown in (2).
+
+(1) Example fo the project config changes with the new label with values
(label name and values are arbitrary)
```
@@ -105,7 +148,7 @@
label-Owner-Approved = -1..+1 group Registered Users
```
-(2) Use a slightly modified version of the previous rules.pl:
+(2) Define the project's rules.pl with an amended version of Example 1:
```prolog
submit_rule(S) :-
@@ -115,3 +158,87 @@
gerrit_owners:add_owner_approval(Approvers, Ds, A),
S =.. [submit | A].
```
+
+Given now an OWNERS configuration of:
+
+```yaml
+inherited: true
+owners:
+ - John Doe
+ - Doug Smith
+```
+
+A change cannot be submitted until John Doe or Doug Smith add a label
+"Owner-Approved", independently from being able to provide any Code-Review.
+
+## Example 4 - Owners based on matchers
+
+Often the ownership comes from the developer's skills and competencies and
+cannot be purely defined by the project's directory structure.
+For instance, all the files ending with .sql should be owned and signed-off by
+the DBA while all the ones ending with .css by approved by the UX Team.
+
+Given an OWNERS configuration of:
+
+```yaml
+inherited: true
+matchers:
+ - suffix: .sql
+ owners:
+ - Mister Dba
+ - suffix: .css
+ owners:
+ - John Creative
+ - Matt Designer
+```
+
+And a rules.pl of:
+
+```prolog
+submit_rule(S) :-
+ gerrit:default_submit(L),
+ L =.. [submit | Sr ],
+ gerrit_owners:add_match_owner_approval(Sr,A),
+ S =.. [submit | A ].
+```
+
+Then for any change that contains files with .sql or .css extensions, besides
+to the default Gerrit submit rules, the extra constraints on the additional
+owners of the modified files will be added. The final submit is enabled if both
+Gerrit default rules are satisfied and all the owners of the .sql files
+(Mister Dba) and the .css files (either John Creative or Matt Designer) have
+provided their Code-Review +2 feedback.
+
+## Example 5 - Owners details on a per-file basis
+
+When using the owners with a series of matchers associated to different set of
+owners, it may not be trivial to understand exactly *why* change is not approved
+yet.
+
+We need to define one extra submit rule to scan the entire list of files in the
+change and their associated owners and cross-check with the existing Code-Review
+feedback received.
+
+Given the same OWNERS and rules.pl configuration of Example 4 with the following
+extra rule:
+
+```prolog
+submit_rule(submit(W)) :-
+ gerrit_owners:findall_match_file_user(W).
+```
+
+For every change that would include any .sql or .css file (e.g. my-update.sql
+and styles.css) Gerrit will display as additional description on the "need" code
+review labels section of the change screen:
+
+```
+Code-Review from owners
+Mister Dba owns my-update.sql
+John Creative, Matt Designer own styles.css
+```
+
+As soon as the owners reviews are provided, the corresponding entry will be
+removed from the "need" section of the change.
+
+In this way, it is always clear which owner needs to provide their feedback on
+which file of the change.
\ No newline at end of file
