properly run ourselves twice (#2807)

[etc/vim.git] / docs / contributing / gauging_changes.md

diff --git a/docs/contributing/gauging_changes.md b/docs/contributing/gauging_changes.md
index 6b70e0bc9bc15dab0c680bd13a0257995d0445cc..9b38fe1b6287f98fe1b3464206693e855459af9f 100644 (file)
--- a/docs/contributing/gauging_changes.md
+++ b/docs/contributing/gauging_changes.md
@@ -37,25 +37,59 @@ If you're running locally yourself to test black on lots of code try:
 
 ### CLI arguments
 
 
 ### CLI arguments
 

-```text
-Usage: black-primer [OPTIONS]
+```{program-output} black-primer --help

 
 

-  primer - prime projects for blackening... 🏴
+```
+
+## diff-shades
+
+diff-shades is a tool similar to black-primer, it also runs _Black_ across a list of Git
+cloneable OSS projects recording the results. The intention is to eventually fully
+replace black-primer with diff-shades as it's much more feature complete and supports
+our needs better.
+
+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. Black-primer's results would usually be filled with changes
+caused by pre-existing code in Black drowning out the (new) changes we want to see. It
+operates similarly to black-primer but crucially it saves the results as a JSON file
+which allows for the rich comparison features alluded to above.
+
+For more information, please see the [diff-shades documentation][diff-shades].

 
 

-Options:
-  -c, --config PATH      JSON config file path  [default: /Users/cooper/repos/
-                         black/src/black_primer/primer.json]
+### CI integration

 
 

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

 
 

-  -w, --workdir PATH     Directory path for repo checkouts  [default: /var/fol
-                         ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200
-                         517125229]
+|                       | 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            |

 
 

-  -W, --workers INTEGER  Number of parallel worker coroutines  [default: 2]
-  -h, --help             Show this message and exit.
+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.
+
+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.
+
+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.
+
+```{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.
+
+Once finished, check the logs or download the artifacts for local use.

 ```
 ```

+
+[diff-shades]: https://github.com/ichard26/diff-shades#readme