actions/black
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
3d96b7f10a
black/docs/contributing/gauging_changes.md
Richard Si 3d96b7f10a
Autogenerate black(d|-primer)? help in usage docs (#2212) 
So these won't go out of date. This does mean the environment has be
setup a bit more carefully so the right version of the tool is used,
but thankfully the build environment is rebuilt on change on RTD anyway.

Also since the HTML docs are known to build fine, let's provide
downloadable HTMLzips of our docs.

This change needs RTD and GH to install Black with the [d] extra so
blackd's help can generated. While editing RTD's config file, let's
migrate the file to a non-deprecated filename.

Also I missed adding AUTHORS.md to the files key in the doc GHA config.
2021-05-09 19:35:56 -07:00

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

black-primer

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

Run flow

  • 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

Speed up runs 🏎

If you're running locally yourself to test black on lots of code try:

  • Using -k / --keep + -w / --work-dir so you don't have to re-checkout the repo each run

CLI arguments