actions/black
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
a41dc89f1f
black/docs/contributing/gauging_changes.md
Richard Si f239d227c0
Enforce no formatting changes for PRs via CI (GH-2951) 
Now PRs will run two diff-shades jobs, "preview-changes" which formats
all projects with preview=True, and "assert-no-changes" which formats
all projects with preview=False. The latter also fails if any changes
were made.

Pushes to main will only run "preview-changes"

Also the workflow_dispatch feature was dropped since it was
complicating everything for little gain.
2022-03-26 17:22:38 -04:00

2.7 KiB
Raw Blame History

Gauging changes

A lot of the time, your change will affect formatting and/or performance. Quantifying these changes is hard, so we have tooling to help make it easier.

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".

diff-shades

diff-shades is a tool that runs Black across a list of open-source 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.

For more information, please see the diff-shades documentation.

CI integration

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 that analyzes and compares two revisions of Black according to these rules:

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

For pushes to main, there's only one analysis job named preview-changes where the preview style is used for all projects.

For PRs they get one more analysis job: assert-no-changes. It's similar to preview-changes but runs with the stable code style. It will fail if changes were made. This makes sure code won't be reformatted again and again within the same year in accordance to Black's stability policy.

Additionally for PRs, a PR comment will be posted embedding a summary of the preview 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 `preview-changes` job will only fail intentionally if while analyzing a file failed to
format. Otherwise a failure indicates a bug in the workflow.

The workflow uploads several artifacts upon completion:

  • The raw analyses (.json)
  • HTML diffs (.html)
  • .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. The HTML diffs come in handy for push-based where there's no PR to post a comment. And the analyses exist just in case you want to do further analysis using the collected data locally.