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

Resolve new flake8-bugbear errors (B020) (GH-2950)
[etc/vim.git] / docs / contributing / gauging_changes.md
index 6b70e0bc9bc15dab0c680bd13a0257995d0445cc..f28e81120b3f5a6b1eeadc330722715b4ca50169 100644 (file)
@@ -7,55 +7,48 @@ It's recommended you evaluate the quantifiable changes your _Black_ formatting
 modification causes before submitting a PR. Think about if the change seems disruptive
 enough to cause frustration to projects that are already "black formatted".
 
-## black-primer
+## diff-shades
 
-`black-primer` is a tool built for CI (and humans) to have _Black_ `--check` a number of
-Git accessible projects in parallel. (configured in `primer.json`) _(A PR will be
-accepted to add Mercurial support.)_
+diff-shades is a tool that runs _Black_ across a list of Git cloneable OSS projects
+recording the results. The main highlight feature of diff-shades is being able to
+compare two revisions of _Black_. This is incredibly useful as it allows us to see what
+exact changes will occur, say merging a certain PR.
 
-### Run flow
+For more information, please see the [diff-shades documentation][diff-shades].
 
-- Ensure we have a `black` + `git` in PATH
-- Load projects from `primer.json`
-- Run projects in parallel with `--worker` workers (defaults to CPU count / 2)
-  - Checkout projects
-  - Run black and record result
-  - Clean up repository checkout _(can optionally be disabled via `--keep`)_
-- Display results summary to screen
-- Default to cleaning up `--work-dir` (which defaults to tempfile schemantics)
-- Return
-  - 0 for successful run
-  - \< 0 for environment / internal error
-  - \> 0 for each project with an error
+### CI integration
 
-### Speed up runs 🏎
+diff-shades is also the tool behind the "diff-shades results comparing ..." /
+"diff-shades reports zero changes ..." comments on PRs. The project has a GitHub Actions
+workflow which runs diff-shades twice against two revisions of _Black_ according to
+these rules:
 
-If you're running locally yourself to test black on lots of code try:
+|                       | Baseline revision       | Target revision              |
+| --------------------- | ----------------------- | ---------------------------- |
+| On PRs                | latest commit on `main` | PR commit with `main` merged |
+| On pushes (main only) | latest PyPI version     | the pushed commit            |
 
-- Using `-k` / `--keep` + `-w` / `--work-dir` so you don't have to re-checkout the repo
-  each run
+Once finished, a PR comment will be posted embedding a summary of the changes and links
+to further information. If there's a pre-existing diff-shades comment, it'll be updated
+instead the next time the workflow is triggered on the same PR.
 
-### CLI arguments
+The workflow uploads 3-4 artifacts upon completion: the two generated analyses (they
+have the .json file extension), `diff.html`, and `.pr-comment.json` if triggered by a
+PR. The last one is downloaded by the `diff-shades-comment` workflow and shouldn't be
+downloaded locally. `diff.html` comes in handy for push-based or manually triggered
+runs. And the analyses exist just in case you want to do further analysis using the
+collected data locally.
 
-```text
-Usage: black-primer [OPTIONS]
+Note that the workflow will only fail intentionally if while analyzing a file failed to
+format. Otherwise a failure indicates a bug in the workflow.
 
-  primer - prime projects for blackening... 🏴
+```{tip}
+Maintainers with write access or higher can trigger the workflow manually from the
+Actions tab using the `workflow_dispatch` event. Simply select "diff-shades"
+from the workflows list on the left, press "Run workflow", and fill in which revisions
+and command line arguments to use.
 
-Options:
-  -c, --config PATH      JSON config file path  [default: /Users/cooper/repos/
-                         black/src/black_primer/primer.json]
-
-  --debug                Turn on debug logging  [default: False]
-  -k, --keep             Keep workdir + repos post run  [default: False]
-  -L, --long-checkouts   Pull big projects to test  [default: False]
-  -R, --rebase           Rebase project if already checked out  [default:
-                         False]
-
-  -w, --workdir PATH     Directory path for repo checkouts  [default: /var/fol
-                         ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200
-                         517125229]
-
-  -W, --workers INTEGER  Number of parallel worker coroutines  [default: 2]
-  -h, --help             Show this message and exit.
+Once finished, check the logs or download the artifacts for local use.
 ```
+
+[diff-shades]: https://github.com/ichard26/diff-shades#readme