]> 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:

Fix typo in file_collection_and_discovery.md (GH-2860)
[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 an obsolete tool (now replaced with `diff-shades`) that was used to
13 gauge the impact of changes in _Black_ on open-source code. It is no longer used
14 internally and will be removed from the _Black_ repository in the future.
15
16 ## diff-shades
17
18 diff-shades is a tool that runs _Black_ across a list of Git cloneable OSS projects
19 recording the results. The main highlight feature of diff-shades is being able to
20 compare two revisions of _Black_. This is incredibly useful as it allows us to see what
21 exact changes will occur, say merging a certain PR.
22
23 For more information, please see the [diff-shades documentation][diff-shades].
24
25 ### CI integration
26
27 diff-shades is also the tool behind the "diff-shades results comparing ..." /
28 "diff-shades reports zero changes ..." comments on PRs. The project has a GitHub Actions
29 workflow which runs diff-shades twice against two revisions of _Black_ according to
30 these rules:
31
32 |                       | Baseline revision       | Target revision              |
33 | --------------------- | ----------------------- | ---------------------------- |
34 | On PRs                | latest commit on `main` | PR commit with `main` merged |
35 | On pushes (main only) | latest PyPI version     | the pushed commit            |
36
37 Once finished, a PR comment will be posted embedding a summary of the changes and links
38 to further information. If there's a pre-existing diff-shades comment, it'll be updated
39 instead the next time the workflow is triggered on the same PR.
40
41 The workflow uploads 3-4 artifacts upon completion: the two generated analyses (they
42 have the .json file extension), `diff.html`, and `.pr-comment.json` if triggered by a
43 PR. The last one is downloaded by the `diff-shades-comment` workflow and shouldn't be
44 downloaded locally. `diff.html` comes in handy for push-based or manually triggered
45 runs. And the analyses exist just in case you want to do further analysis using the
46 collected data locally.
47
48 Note that the workflow will only fail intentionally if while analyzing a file failed to
49 format. Otherwise a failure indicates a bug in the workflow.
50
51 ```{tip}
52 Maintainers with write access or higher can trigger the workflow manually from the
53 Actions tab using the `workflow_dispatch` event. Simply select "diff-shades"
54 from the workflows list on the left, press "Run workflow", and fill in which revisions
55 and command line arguments to use.
56
57 Once finished, check the logs or download the artifacts for local use.
58 ```
59
60 [diff-shades]: https://github.com/ichard26/diff-shades#readme