Improved documentation.
Some additional examples and some additional notes to make it easier
to configure and use the plugin
Change-Id: If35d79949c00265a9290396d58547ab2df77d89b
diff --git a/README.md b/README.md
index b722578..b2dde16 100644
--- a/README.md
+++ b/README.md
@@ -1,50 +1,40 @@
# Gerrit OWNERS Plugin
-This plugin provides a Prolog predicate `add_owner_approval/3` that appends `label('Owner-Approval', need(_))` to a provided list.
+This plugin provides some Prolog predicates that can be used to add customized
+validation checks based on the approval of ‘path owners’ of a particular folder
+in the project.
-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.
+That allows creating a single big project including multiple components and
+users have different roles depending on the particular path where changes are
+being proposed. A user can be “owner” in a specific directory, and thus
+influencing the approvals of changes there, but cannot do the same in others
+paths, so assuring a kind of dynamic subproject access rights.
-The OWNERS files are represented by the following YAML structure:
+## How it works
-```yaml
-inherited: true
-owners:
-- user-a@example.com
-- user-b@example.com
-```
+There are currently two main prolog public verbs:
-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.
+`add_owner_approval/3` (UserList, InList, OutList)
+appends `label('Owner-Approval', need(_))` to InList building OutList if
+UserList has no users contained in the defined owners of this path change.
-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.)
+In other words, the predicate just copies InList to OutList if at least one of
+the elements in UserList is an owner.
-For example, imagine the following tree:
+`add_owner_approval/2` (InList, OutList)
+appends `label('Owner-Approval', need(_))` to InList building OutList if
+no owners has given a Code-Review +2 to this path change.
-```
-/OWNERS
-/example/src/main/OWNERS
-/example/src/main/java/com/example/foo/Foo.java
-/example/src/main/resources/config.properties
-/example/src/test/OWNERS
-/example/src/test/java/com/example/foo/FooTest.java
-```
+This predicate is similar to the first one but generates a UserList with an
+hardcoded policy.
-If you submit a patch set that changes `/example/src/main/java/com/example/foo/Foo.java` then the plugin will first open `/example/src/main/OWNERS` and if inherited is set to true combine it with the owners listed in `/OWNERS`.
+Since add_owner_approval/3 is not using hard coded policies, it can be suitable
+for complex customizations.
-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(_))`.
-Here’s a sample rules.pl that uses this predicate to enable the submit rule.
-
-```prolog
-submit_rule(S) :-
- gerrit:default_submit(D),
- D =.. [submit | Ds],
- findall(U, gerrit:commit_label(label('Code-Review', 2), U), Approvers),
- gerrit_owners:add_owner_approval(Approvers, Ds, A),
- S =.. [submit | A].
-```
## Auto assigner
-There is a second plugin, `gerrit-owners-autoassign` which depends on `gerrit-owners`. It will automatically assign
-all of the owners to review a change when it's created or updated.
+There is a second plugin, gerrit-owners-autoassign which depends on
+gerrit-owners. It will automatically assign all of the owners to review a
+change when it's created or updated.
