Add .md files.
Change-Id: I31c493ddff5b2b117722bb9f57b14bb1cc36187a
diff --git a/src/main/resources/Documentation/about.md b/src/main/resources/Documentation/about.md
new file mode 100644
index 0000000..839f738
--- /dev/null
+++ b/src/main/resources/Documentation/about.md
@@ -0,0 +1,19 @@
+This plugin works with Gerrit projects that
+use Android or Chromium compatible **OWNERS** files.
+The **OWNERS** files specify *owners*, or active maintainers,
+of a project and its directories or files.
+Changes to those files or directories will
+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).
+
+A **`Find Owners`** button is added to the Gerrit revision screen
+if a change needs owner approval. The button pops up a window that contains
+* current reviewers and owners of changed files for users to select, and
+* optionally 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/build.md b/src/main/resources/Documentation/build.md
new file mode 100644
index 0000000..34e8176
--- /dev/null
+++ b/src/main/resources/Documentation/build.md
@@ -0,0 +1,56 @@
+Build
+=====
+
+This plugin is built using Bazel.
+Only the Gerrit in-tree build is supported.
+
+Clone or link this plugin to the plugins directory of Gerrit's source
+tree.
+
+```bash
+git clone https://gerrit.googlesource.com/gerrit
+git clone https://gerrit.googlesource.com/plugins/find-owners
+cd gerrit/plugins
+ln -s ../../find-owners .
+```
+
+Put the external dependency Bazel build file into the Gerrit /plugins
+directory, replacing the existing empty one.
+
+```bash
+cd gerrit/plugins
+rm external_plugin_deps.bzl
+ln -s find-owners/external_plugin_deps.bzl .
+```
+
+From Gerrit source tree issue the command:
+
+```bash
+bazel build plugins/find-owners
+```
+
+The output is created in
+
+```bash
+bazel-genfiles/plugins/find-owners/find-owners.jar
+```
+
+To execute the tests run:
+
+```bash
+bazel test plugins/find-owners:findowners_tests
+```
+
+or filtering using the comma separated tags:
+
+```bash
+bazel test --test_tag_filters=findowners //...
+```
+
+This project can be imported into the Eclipse IDE.
+Add the plugin name to the `CUSTOM_PLUGINS` set in
+Gerrit core in `tools/bzl/plugins.bzl`, and execute:
+
+```bash
+./tools/eclipse/project.py
+```
diff --git a/src/main/resources/Documentation/config.md b/src/main/resources/Documentation/config.md
new file mode 100644
index 0000000..91dfea0
--- /dev/null
+++ b/src/main/resources/Documentation/config.md
@@ -0,0 +1,145 @@
+Configuration
+=============
+
+## The **`submit_rule`** and **`submit_filter`**
+
+To enforce the *owner-approval-before-submit* rule, this plugin provides
+**`find_owners:submit_rule/1`** and **`find_owners:submit_filter/2`**
+predicates for Gerrit projects.
+
+If a Gerrit project wants to enforce this *owner-approval* policy,
+it can add a `submit_rule` to its `rules.pl` file like this:
+
+```prolog
+submit_rule(S) :- find_owners:submit_rule(S).
+```
+
+If many projects need this *owner-approval* policy,
+each of them can have a `submit_rule` defined, or we can simply
+define a `submit_filter` in their common parent project's
+`rules.pl` file like this:
+
+```prolog
+submit_filter(In, Out) :- find_owners:submit_filter(In, Out).
+```
+
+By default the `find_owners:submit_rule` calls `gerrit:default_submit`,
+and the `find_owners:submit_filter` passes `In` to `Out`.
+They add special labels to the output to indicate if *owner* approval
+is needed or missing.
+
+* If a change does not need owner approval, `label('Owner-Approved', may(_))`
+ is added. This is an *optional* requirement that does not affect
+ a change's submittability.
+* If a change needs owner approval, and all changed files have at least one
+ *owner* voted +1 and no negative vote,
+ `label('Owner-Approved', ok(user(1)))` is added.
+* If a change needs owner approval, but some changed file has no *owner*
+ +1 vote or has negative *owner* vote,
+ `label('Owner-Review-Vote', need(_))` is added.
+ This will make a change *not-submittable*.
+ The change author should add missing *owners* to the
+ reviewers list and/or ask for those owner's +1 Code-Review votes.
+ The **`Find Owners`** button is useful in this situation to find
+ the missing *owners* or +1 votes of any changed files.
+
+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`.
+
+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
+
+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.
+
+## Example 0, call `submit_filter/2`
+
+The simplest configuration adds to `rules.pl` of the root
+`All-Projects` project.
+
+```prolog
+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.
+
+## 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.
+
+```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.
+
+```prolog
+submit_filter(In, Out) :- find_owners:submit_filter(In, Out, 2).
+```
+
+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.
+
+```bash
+[plugin "find-owners"]
+ minOwnerVoteLevel = 2
+```
+
+## Example 4, call `remove_may_label/2`
+
+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.
+
+```prolog
+submit_filter(In, Out) :-
+ find_owners:submit_filter(In, Temp),
+ find_owners:remove_may_label(Temp, Out).
+```
+
+## Example 5, call `remove_need_label/2`
+
+To make all changes with some special property,
+e.g., from the auto merger, exempt from owner approval,
+we can add a special filter to `rules.pl` of the root `All-Projects` project.
+
+```prolog
+submit_filter(In, Out) :-
+ is_exempt_from_owner_approval(), % define-your-own-rule
+ find_owners:remove_need_label(In, Out).
+```
+
+## Example 6, define `addDebugMsg`
+
+Add the following to global `gerrit.config`
+or a project's `project.config` file,
+to debug the find-owners plugin.
+
+```bash
+[plugin "find-owners"]
+ addDebugMsg = true
+```
diff --git a/src/main/resources/Documentation/rest-api.md b/src/main/resources/Documentation/rest-api.md
new file mode 100644
index 0000000..2e792b6
--- /dev/null
+++ b/src/main/resources/Documentation/rest-api.md
@@ -0,0 +1,75 @@
+REST API to Get Owners Info
+===========================
+
+Any Gerrit UI clients or tools can use the
+`plugins/find-owners/change/<id>` API to get
+OWNERS information of a change.
+
+### Request
+
+```bash
+GET /plugins/find-owners/change/<id> HTTP/1.0
+```
+
+The `<id>` is a Gerrit change ID. This API can have two parameters:
+
+* **patchset**: is the patchset number of the change to look for changed files.
+ By default the current (latest) patchset of given change is used.
+
+* **debug**: can be set to true or false to override the configuration variable
+ **addDebugMsg**.
+
+For example,
+
+```bash
+http://.../plugins/find-owners/change/29?debug=true&patchset=3
+```
+
+### Response
+
+This API returns a JSON object with the following attributes:
+
+* **minOwnerVoteLevel**: is 1 by default, but could be set to 2.
+ It is the minimal Code-Review vote value all changed files must get
+ from at least one owner to make a change submittable.
+
+* **addDebugMsg**: is false by default. In a development/test configuration,
+ this attribute could be true, to tell a client to display extra debug
+ information.
+
+* **change**: is the change number.
+
+* **patchset**: is the change patchset number.
+
+* **owner\_revision**: is the revision where OWNERS files were searched.
+ It is the tip of the given change's destination branch.
+ Due to caching this revision might be behind recent branches changes.
+
+* **dbgmsgs**: returned only when addDebugMsg is true,
+ a set of debugging messages including project name, branch name,
+ server address, etc.
+
+* **path2owners**: returned only when addDebugMsg is true,
+ a map from directory path or file glob to a string of owner emails
+ separated by space. Note that `*` is a special owner email address.
+ It means that there is no owner and anyone can be the owner.
+ Included directories are those affected by the change revision.
+
+* **owner2paths**: returned only when addDebugMsg is true,
+ a map from owner email to directory path or file glob.
+ This is opposite to the path2owners map.
+
+* **file2owners**: a map from each file in the change patchset to
+ the file owner emails, separated by space.
+
+* **reviewers**: an array of current reviewer emails followed by
+ optional extra information that should be ignored for now.
+
+* **owners**: an array of owner emails followed by the owner weights,
+ `[n1+n2+n3]`, which are the number of level 1, 2, 3+ controlled files.
+ This list of owners are the keys in the owner2paths map.
+ The array is sorted by owner weights.
+ Users should try to pick owners with more weights to review a change.
+
+* **files**: an alphabetically sorted files changed
+ in the given change patchset.
diff --git a/src/main/resources/Documentation/syntax.md b/src/main/resources/Documentation/syntax.md
new file mode 100644
index 0000000..54db99f
--- /dev/null
+++ b/src/main/resources/Documentation/syntax.md
@@ -0,0 +1,31 @@
+OWNERS File Syntax
+==================
+
+Owner approval is based on OWNERS files located in the same
+repository and top of the _merge-to_ branch of a patch set.
+
+The syntax is:
+
+```java
+lines := (SPACE* line? SPACE* EOL)*
+line := "set noparent"
+ | "per-file" SPACE+ glob SPACE* "=" SPACE* directive
+ | comment
+ | directive
+directive := email
+ | "*"
+glob := [a-zA-Z0-9_-*?]+
+comment := "#" ANYCHAR*
+email := [^ @]+@[^ #]+
+ANYCHAR := any character but EOL
+EOL := end of line characters
+SPACE := any white space character
+```
+
+* `per-file glob = directive` applies `directive` only to files
+ matching `glob`, which does not contain directory path.
+
+* The email addresses should belong to registered Gerrit users.
+
+* The `*` directive means that no owner is specified for the directory
+ or file. Any user can approve that directory or file.
