docs/infra/watchlists.md

## What are watchlists?

A watchlist is a mechanism that allows a developer (a "watcher") to watch over
portions of code that the watcher is interested in. A watcher will be cc-ed on
changes that modify that portion of code, thereby giving that watcher an
opportunity to make comments on codereview.chromium.org even before the change
is committed.

**Important :** As watchlists are processed locally when uploading using `git cl
upload` it is not possible to define watchlists for Gerrit CLs generated by
tools such as the [Skia autoroller][skia-autoroller] (see
[crbug.com/982198][crbug-982198]). In order to be notified of autoroller
commits, find the [corresponding config file][roller-configs] and add email
addresses of people to be notified of roller commits in the `sheriff` field of
the autoroller config.

## Syntax

Watchlists are defined using a `WATCHLISTS` file, which resides at the root of a
repository. A typical `WATCHLISTS` file looks like:

```
{
  'WATCHLIST_DEFINITIONS': {
    'valgrind': {
      'filepath': 'tools/valgrind/',
    },
    'mac': {
      'filepath': 'cocoa|\.mm$|(_mac|_posix)\.(cc|h)$',
    },
  },
  'WATCHLISTS': {
    'valgrind': ['nirnimesh@chromium.org', 'dank@chromium.org'],
  },
}
```

In this case, watchlists named `valgrind` and `mac` are defined in
`WATCHLIST_DEFINITIONS` and their corresponding watchers declared in
`WATCHLISTS`.

In the example above, whenever a new changeset is created that refers to any
file in `tools/valgrind/`, the `'valgrind'` watchlist will be triggered and
`nirnimesh@chromium.org` & `dank@chromium.org` will be cc-ed to the changeset
for review. A regular expression can be used as the matching pattern. Matches
are determined using python's `re.search()` function call, so matching `A_WORD`
is the same as matching `.*A_WORD.*`.

Each name in `WATCHLISTS` must be defined first in `WATCHLIST_DEFINITIONS`.

Watchlist processing takes place during `git-cl upload` and are non-binding;
that is, an approval from that watcher is not needed for commit. It merely gives
the watcher an opportunity to make comments, if any.

## Editing Watchlists

You create new watchlists or add yourself to existing watchlists by editing the
WATCHLISTS file at the base of the repository.

It's advisable to run `watchlists.py` to verify that your new rules work.

Example (from src):

```
python ../depot_tools/watchlists.py PATH/TO/FILE1 PATH/TO/FILE2 ....
```


## Override

To override watchlist processing, use `git cl upload` with `--bypass-hooks`.

[//]: # (the reference link section should be alphabetically sorted)
[skia-autoroller]: https://skia.googlesource.com/buildbot/+/master/autoroll/README.md
[crbug-982198]: https://bugs.chromium.org/p/chromium/issues/detail?id=982198
[roller-configs]: https://skia.googlesource.com/buildbot/+/master/autoroll/config