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

Define a stability policy (#2529)
[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 ```