1## What are watchlists?
2
3A watchlist is a mechanism that allows a developer (a "watcher") to watch over
4portions of code that the watcher is interested in. A watcher will be cc-ed on
5changes that modify that portion of code, thereby giving that watcher an
6opportunity to make comments on chromium-review.googlesource.com even before the
7change is committed.
8
9**Important :** As watchlists are processed locally when uploading using `git cl
10upload` it is not possible to define watchlists for Gerrit CLs generated by
11tools such as the [Skia autoroller][skia-autoroller] (see
12[crbug.com/982198][crbug-982198]). In order to be notified of autoroller
13commits, find the [corresponding config file][roller-configs] and add email
14addresses of people to be notified of roller commits in the `sheriff` field of
15the autoroller config.
16
17## Syntax
18
19Watchlists are defined using a `WATCHLISTS` file, which resides at the root of a
20repository. A typical `WATCHLISTS` file looks like:
21
22```
23{
24  'WATCHLIST_DEFINITIONS': {
25    'valgrind': {
26      'filepath': 'tools/valgrind/',
27    },
28    'mac': {
29      'filepath': 'cocoa|\.mm$|(_mac|_posix)\.(cc|h)$',
30    },
31  },
32  'WATCHLISTS': {
33    'valgrind': ['nirnimesh@chromium.org', 'dank@chromium.org'],
34  },
35}
36```
37
38In this case, watchlists named `valgrind` and `mac` are defined in
39`WATCHLIST_DEFINITIONS` and their corresponding watchers declared in
40`WATCHLISTS`.
41
42In the example above, whenever a new changeset is created that refers to any
43file in `tools/valgrind/`, the `'valgrind'` watchlist will be triggered and
44`nirnimesh@chromium.org` & `dank@chromium.org` will be cc-ed to the changeset
45for review. A regular expression can be used as the matching pattern. Matches
46are determined using python's `re.search()` function call, so matching `A_WORD`
47is the same as matching `.*A_WORD.*`.
48
49Each name in `WATCHLISTS` must be defined first in `WATCHLIST_DEFINITIONS`.
50
51Watchlist processing takes place during `git-cl upload` and are non-binding;
52that is, an approval from that watcher is not needed for commit. It merely gives
53the watcher an opportunity to make comments, if any.
54
55## Editing Watchlists
56
57You create new watchlists or add yourself to existing watchlists by editing the
58WATCHLISTS file at the base of the repository.
59
60It's advisable to run `watchlists.py` to verify that your new rules work.
61
62Example (from src):
63
64```
65python ../depot_tools/watchlists.py PATH/TO/FILE1 PATH/TO/FILE2 ....
66```
67
68
69## Override
70
71To override watchlist processing, use `git cl upload` with `--bypass-hooks`.
72
73[//]: # (the reference link section should be alphabetically sorted)
74[skia-autoroller]: https://skia.googlesource.com/buildbot/+/master/autoroll/README.md
75[crbug-982198]: https://bugs.chromium.org/p/chromium/issues/detail?id=982198
76[roller-configs]: https://skia.googlesource.com/buildbot/+/master/autoroll/config
77