util/gerrit-bot/README.md

   1 ## Gerrit Bot
   2
   3 ### Getting Username and Password
   4
   5 * Follow this link
   6 [https://gem5-review.googlesource.com/new-password](https://gem5-review.googlesource.com/new-password)
   7 and copy the authenticating script to a file, supposedly `gerrit_auth_script`.
   8
   9 * After that, run the `extract_gitcookies.py` to extract the username and
  10 password from the obtained script.
  11 For example, the following command extracts the username and password from
  12 `gerrit_auth_script` and writes them to `GEM5_BOT_AUTH_INFO`,
  13 ```sh
  14 python3 extract_gitcookies.py gerrit_auth_script GEM5_BOT_AUTH_INFO
  15 ```
  16 The `GEM5_BOT_AUTH_INFO` will have two lines: the first line contains the
  17 username and the second line is the corresponding password.
  18 **Notes:**
  19 * The above link, [https://gem5-review.googlesource.com/new-password](https://gem5-review.googlesource.com/new-password),
  20 generates a new pair of username and password per visit.
  21 * The `extract_gitcookies.py` file is also able to read from `.gitcookies`
  22 file. For example, `python3 extract_gitcookies.py ~/.gitcookies output`
  23 will write all pairs of username and password in two lines per pair to
  24 `output`.
  25 * The gerrit-bot only reads the pair of username and password appearing
  26 in the first and the second line in the `GEM5_BOT_AUTH_INFO` file.
  27
  28 ### Gerrit Bot
  29
  30 **Notes:** this is likely to be changed.
  31
  32 The idea of implementing the bot is as follows,
  33 * The `Configs` class should contain all constants that are configurable
  34 prior to running.
  35 * Classes such as `LabelInfo` and `ReviewInput` are simplied versions
  36 resembling those data structures of the same name according to the
  37 [Gerrit REST API documentation](https://gerrit-review.googlesource.com/Documentation/rest-api.html#_endpoints).
  38 * In the class `GerritRestAPIRequester`,
  39     * The `__generate_*_request()` functions should be a one-to-one function
  40 to a set of Gerrit REST API endpoints. The functions should generate a
  41 `requests.Request` object.
  42     * The `send_*()` functions are adapted to a more specific use case.
  43
  44 ### Gerrit API
  45 * Query options: [https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#query-options](https://gerrit-review.googlesource.com/Documentation/rest-api-changes.html#query-options)
  46
  47 ### Appendix I. `extract_gitcookies.py`
  48 This script extracts all pairs of username and password from the gerrit
  49 authentication script from a file or a .gitcookies file.
  50
  51 The usage of the script is as follows,
  52 ```sh
  53 python3 extract_gitcookies.py input_path output_path
  54 ```
  55
  56 ### Appendix II. `MAINTAINERS.json`
  57 This file should be consistent with the file `MAINTAINERS`.