chromium/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 chromium-review.googlesource.com even before the
change is committed.

## 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': ['[email protected]', '[email protected]'],
  },
}
```

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
`[email protected]` & `[email protected]` 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 on Gerrit with the "Watchlists" analyzer and is
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 third_party/depot_tools/watchlists.py PATH/TO/FILE1 PATH/TO/FILE2 ....
```