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 ```{program-output} black-primer --help
  41
  42 ```
  43
  44 ## diff-shades
  45
  46 diff-shades is a tool similar to black-primer, it also runs _Black_ across a list of Git
  47 cloneable OSS projects recording the results. The intention is to eventually fully
  48 replace black-primer with diff-shades as it's much more feature complete and supports
  49 our needs better.
  50
  51 The main highlight feature of diff-shades is being able to compare two revisions of
  52 _Black_. This is incredibly useful as it allows us to see what exact changes will occur,
  53 say merging a certain PR. Black-primer's results would usually be filled with changes
  54 caused by pre-existing code in Black drowning out the (new) changes we want to see. It
  55 operates similarly to black-primer but crucially it saves the results as a JSON file
  56 which allows for the rich comparison features alluded to above.
  57
  58 For more information, please see the [diff-shades documentation][diff-shades].
  59
  60 ### CI integration
  61
  62 diff-shades is also the tool behind the "diff-shades results comparing ..." /
  63 "diff-shades reports zero changes ..." comments on PRs. The project has a GitHub Actions
  64 workflow which runs diff-shades twice against two revisions of _Black_ according to
  65 these rules:
  66
  67 |                       | Baseline revision       | Target revision              |
  68 | --------------------- | ----------------------- | ---------------------------- |
  69 | On PRs                | latest commit on `main` | PR commit with `main` merged |
  70 | On pushes (main only) | latest PyPI version     | the pushed commit            |
  71
  72 Once finished, a PR comment will be posted embedding a summary of the changes and links
  73 to further information. If there's a pre-existing diff-shades comment, it'll be updated
  74 instead the next time the workflow is triggered on the same PR.
  75
  76 The workflow uploads 3-4 artifacts upon completion: the two generated analyses (they
  77 have the .json file extension), `diff.html`, and `.pr-comment.json` if triggered by a
  78 PR. The last one is downloaded by the `diff-shades-comment` workflow and shouldn't be
  79 downloaded locally. `diff.html` comes in handy for push-based or manually triggered
  80 runs. And the analyses exist just in case you want to do further analysis using the
  81 collected data locally.
  82
  83 Note that the workflow will only fail intentionally if while analyzing a file failed to
  84 format. Otherwise a failure indicates a bug in the workflow.
  85
  86 ```{tip}
  87 Maintainers with write access or higher can trigger the workflow manually from the
  88 Actions tab using the `workflow_dispatch` event. Simply select "diff-shades"
  89 from the workflows list on the left, press "Run workflow", and fill in which revisions
  90 and command line arguments to use.
  91
  92 Once finished, check the logs or download the artifacts for local use.
  93 ```
  94
  95 [diff-shades]: https://github.com/ichard26/diff-shades#readme