From 99f251cbca07268415935d646445991cf155e542 Mon Sep 17 00:00:00 2001
From: "W. Trevor King" <wking@tremily.us>
Date: Tue, 28 Aug 2018 16:46:22 -0700
Subject: [PATCH] contributors/guide/owners: Document OWNERS' 'filters' key

Catching up with kubernetes/test-infra@e8c6b7f1 (Add OWNERS file
support for regexp filters, 2018-01-08, kubernetes/test-infra#6411).

The relative-path assertion is based on Cole's comment [1].  The
sibling limitation is based on Cole's comment [2].

[1]: https://github.com/kubernetes/community/pull/2596#discussion_r213768438
[2]: https://github.com/kubernetes/community/pull/2596#discussion_r213788099
---
 contributors/guide/owners.md | 44 ++++++++++++++++++++++++++++++++++--
 1 file changed, 42 insertions(+), 2 deletions(-)

diff --git a/contributors/guide/owners.md b/contributors/guide/owners.md
index 0700e70aa..021d28e84 100644
--- a/contributors/guide/owners.md
+++ b/contributors/guide/owners.md
@@ -34,12 +34,14 @@ OWNERS files are in YAML format and support the following keys:
     effect on `a/deep/nested/bit/of/code`
 - `reviewers`: a list of GitHub usernames or aliases that are good candidates to `/lgtm` a PR
 
+The above keys constitute a *simple OWNERS configuration*.
+
 All users are expected to be assignable. In GitHub terms, this means they are either collaborators
 of the repo, or members of the organization to which the repo belongs.
 
 A typical OWNERS file looks like:
 
-```
+```yaml
 approvers:
   - alice
   - bob     # this is a comment
@@ -49,6 +51,41 @@ reviewers:
   - sig-foo # this is an alias
 ```
 
+#### Filters
+
+An OWNERS file may also include a `filters` key.
+The `filters` key is a map whose keys are [Go regular expressions][go-regex] and whose values are [simple OWNERS configurations](#owners).
+The regular expression keys are matched against paths relative to the OWNERS file in which the keys are declared.
+For example:
+
+```yaml
+filters:
+  ".*":
+    labels:
+    - re/all
+  "\\.go$":
+    labels:
+    - re/go
+```
+
+If you set `filters` you must not set a [simple OWNERS configuration](#owners) outside of `filters`.
+For example:
+
+```yaml
+# WARNING: This use of 'labels' and 'filters' as siblings is invalid.
+labels:
+- re/all
+filters:
+  "\\.go$":
+    labels:
+    - re/go
+```
+
+Instead, set a `.*` key inside `filters` (as shown in the previous example).
+
+**WARNING**: The `approve` plugin [does not currently respect `filters`][test-infra-7690].
+Until that is fixed, `filters` should only be used for the the `labels` key (as shown in the above example).
+
 ### OWNERS_ALIASES
 
 Each repo may contain at its root an OWNERS_ALIAS file.
@@ -62,7 +99,7 @@ publicly auditable.
 
 A sample OWNERS_ALISES file looks like:
 
-```
+```yaml
 aliases:
   sig-foo:
     - david
@@ -257,3 +294,6 @@ Good examples of OWNERS usage:
 - there are more `reviewers` than `approvers`
 - the `approvers` are not in the `reviewers` section
 - OWNERS files that are regularly updated (at least once per release)
+
+[go-regex]: https://golang.org/pkg/regexp/#pkg-overview
+[test-infra-7690]: https://github.com/kubernetes/test-infra/issues/7690