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