docs/contributing/gauging_changes.md

   1 # Gauging changes
   2
   3 A lot of the time, your change will affect formatting and/or performance. Quantifying
   4 these changes is hard, so we have tooling to help make it easier.
   5
   6 It's recommended you evaluate the quantifiable changes your _Black_ formatting
   7 modification causes before submitting a PR. Think about if the change seems disruptive
   8 enough to cause frustration to projects that are already "black formatted".
   9
  10 ## black-primer
  11
  12 `black-primer` is a tool built for CI (and humans) to have _Black_ `--check` a number of
  13 Git accessible projects in parallel. (configured in `primer.json`) _(A PR will be
  14 accepted to add Mercurial support.)_
  15
  16 ### Run flow
  17
  18 - Ensure we have a `black` + `git` in PATH
  19 - Load projects from `primer.json`
  20 - Run projects in parallel with `--worker` workers (defaults to CPU count / 2)
  21   - Checkout projects
  22   - Run black and record result
  23   - Clean up repository checkout _(can optionally be disabled via `--keep`)_
  24 - Display results summary to screen
  25 - Default to cleaning up `--work-dir` (which defaults to tempfile schemantics)
  26 - Return
  27   - 0 for successful run
  28   - \< 0 for environment / internal error
  29   - \> 0 for each project with an error
  30
  31 ### Speed up runs 🏎
  32
  33 If you're running locally yourself to test black on lots of code try:
  34
  35 - Using `-k` / `--keep` + `-w` / `--work-dir` so you don't have to re-checkout the repo
  36   each run
  37
  38 ### CLI arguments
  39
  40 ```text
  41 Usage: black-primer [OPTIONS]
  42
  43   primer - prime projects for blackening... 🏴
  44
  45 Options:
  46   -c, --config PATH      JSON config file path  [default: /Users/cooper/repos/
  47                          black/src/black_primer/primer.json]
  48
  49   --debug                Turn on debug logging  [default: False]
  50   -k, --keep             Keep workdir + repos post run  [default: False]
  51   -L, --long-checkouts   Pull big projects to test  [default: False]
  52   -R, --rebase           Rebase project if already checked out  [default:
  53                          False]
  54
  55   -w, --workdir PATH     Directory path for repo checkouts  [default: /var/fol
  56                          ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200
  57                          517125229]
  58
  59   -W, --workers INTEGER  Number of parallel worker coroutines  [default: 2]
  60   -h, --help             Show this message and exit.
  61 ```