]> git.madduck.net Git - etc/vim.git/blob - docs/contributing/gauging_changes.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Bump sphinx from 4.3.2 to 4.4.0 in /docs (#2776)
[etc/vim.git] / 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-body.md` 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