]> git.madduck.net Git - etc/vim.git/blob - docs/black_primer.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:

4d6ce27e037e76bf5a55db6b425527b4af1af028
[etc/vim.git] / docs / black_primer.md
1 # black-primer
2
3 `black-primer` is a tool built for CI (and humans) to have _Black_ `--check` a number of
4 (configured in `primer.json`) Git accessible projects in parallel. _(A PR will be
5 accepted to add Mercurial support.)_
6
7 ## Run flow
8
9 - Ensure we have a `black` + `git` in PATH
10 - Load projects from `primer.json`
11 - Run projects in parallel with `--worker` workers (defaults to CPU count / 2)
12   - Checkout projects
13   - Run black and record result
14   - Clean up repository checkout _(can optionally be disabled via `--keep`)_
15 - Display results summary to screen
16 - Default to cleaning up `--work-dir` (which defaults to tempfile schemantics)
17 - Return
18   - 0 for successful run
19   - < 0 for environment / internal error
20   - \> 0 for each project with an error
21
22 ## Speed up runs 🏎
23
24 If you're running locally yourself to test black on lots of code try:
25
26 - Using `-k` / `--keep` + `-w` / `--work-dir` so you don't have to re-checkout the repo
27   each run
28
29 ## CLI arguments
30
31 ```text
32 Usage: black-primer [OPTIONS]
33
34   primer - prime projects for blackening... 🏴
35
36 Options:
37   -c, --config PATH      JSON config file path  [default: /Users/cooper/repos/
38                          black/src/black_primer/primer.json]
39
40   --debug                Turn on debug logging  [default: False]
41   -k, --keep             Keep workdir + repos post run  [default: False]
42   -L, --long-checkouts   Pull big projects to test  [default: False]
43   -R, --rebase           Rebase project if already checked out  [default:
44                          False]
45
46   -w, --workdir PATH     Directory path for repo checkouts  [default: /var/fol
47                          ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200
48                          517125229]
49
50   -W, --workers INTEGER  Number of parallel worker coroutines  [default: 2]
51   -h, --help             Show this message and exit.
52 ```
53
54 ## primer config file
55
56 The config is JSON format. Its main element is the `"projects"` dictionary. Below
57 explains each parameter:
58
59 ```json
60 {
61   "projects": {
62     "00_Example": {
63       "cli_arguments": "List of extra CLI arguments to pass Black for this project",
64       "expect_formatting_changes": "Boolean to indicate that the version of Black is expected to cause changes",
65       "git_clone_url": "URL you would pass `git clone` to check out this repo",
66       "long_checkout": "Boolean to have repo skipped by default unless `--long-checkouts` is specified",
67       "py_versions": "List of major Python versions to run this project with - all will do as you'd expect - run on ALL versions"
68     },
69     "aioexabgp": {
70       "cli_arguments": [],
71       "expect_formatting_changes": true,
72       "git_clone_url": "https://github.com/cooperlees/aioexabgp.git",
73       "long_checkout": false,
74       "py_versions": ["all", "3.8"] // "all" ignores all other versions
75     }
76   }
77 }
78 ```
79
80 ## Example run
81
82 ```console
83 cooper-mbp:black cooper$ ~/venvs/b/bin/black-primer
84 [2020-05-17 13:06:40,830] INFO: 4 projects to run Black over (lib.py:270)
85 [2020-05-17 13:06:44,215] INFO: Analyzing results (lib.py:285)
86 -- primer results 📊 --
87
88 3 / 4 succeeded (75.0%) ✅
89 1 / 4 FAILED (25.0%) 💩
90  - 0 projects disabled by config
91  - 0 projects skipped due to Python version
92  - 0 skipped due to long checkout
93
94 Failed projects:
95
96 ## flake8-bugbear:
97  - Returned 1
98  - stdout:
99 --- tests/b303_b304.py  2020-05-17 20:04:09.991227 +0000
100 +++ tests/b303_b304.py  2020-05-17 20:06:42.753851 +0000
101 @@ -26,11 +26,11 @@
102      maxint = 5  # this is okay
103      # the following shouldn't crash
104      (a, b, c) = list(range(3))
105      # it's different than this
106      a, b, c = list(range(3))
107 -    a, b, c, = list(range(3))
108 +    a, b, c = list(range(3))
109      # and different than this
110      (a, b), c = list(range(3))
111      a, *b, c = [1, 2, 3, 4, 5]
112      b[1:3] = [0, 0]
113
114 would reformat tests/b303_b304.py
115 Oh no! 💥 💔 💥
116 1 file would be reformatted, 22 files would be left unchanged.
117 ```