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 ## diff-shades
  11
  12 diff-shades is a tool that runs _Black_ across a list of open-source projects recording
  13 the results. The main highlight feature of diff-shades is being able to compare two
  14 revisions of _Black_. This is incredibly useful as it allows us to see what exact
  15 changes will occur, say merging a certain PR.
  16
  17 For more information, please see the [diff-shades documentation][diff-shades].
  18
  19 ### CI integration
  20
  21 diff-shades is also the tool behind the "diff-shades results comparing ..." /
  22 "diff-shades reports zero changes ..." comments on PRs. The project has a GitHub Actions
  23 workflow that analyzes and compares two revisions of _Black_ according to these rules:
  24
  25 |                       | Baseline revision       | Target revision              |
  26 | --------------------- | ----------------------- | ---------------------------- |
  27 | On PRs                | latest commit on `main` | PR commit with `main` merged |
  28 | On pushes (main only) | latest PyPI version     | the pushed commit            |
  29
  30 For pushes to main, there's only one analysis job named `preview-changes` where the
  31 preview style is used for all projects.
  32
  33 For PRs they get one more analysis job: `assert-no-changes`. It's similar to
  34 `preview-changes` but runs with the stable code style. It will fail if changes were
  35 made. This makes sure code won't be reformatted again and again within the same year in
  36 accordance to Black's stability policy.
  37
  38 Additionally for PRs, a PR comment will be posted embedding a summary of the preview
  39 changes and links to further information. If there's a pre-existing diff-shades comment,
  40 it'll be updated instead the next time the workflow is triggered on the same PR.
  41
  42 ```{note}
  43 The `preview-changes` job will only fail intentionally if while analyzing a file failed to
  44 format. Otherwise a failure indicates a bug in the workflow.
  45 ```
  46
  47 The workflow uploads several artifacts upon completion:
  48
  49 - The raw analyses (.json)
  50 - HTML diffs (.html)
  51 - `.pr-comment.json` (if triggered by a PR)
  52
  53 The last one is downloaded by the `diff-shades-comment` workflow and shouldn't be
  54 downloaded locally. The HTML diffs come in handy for push-based where there's no PR to
  55 post a comment. And the analyses exist just in case you want to do further analysis
  56 using the collected data locally.
  57
  58 [diff-shades]: https://github.com/ichard26/diff-shades#readme