Format the Wagtail codebase with black

[thibaudcolas]

We’ve discussed reformatting Wagtail’s codebase with black multiple times in the past, but it seems there is no public record of those discussions / why we haven’t done it yet but intend to.

Here is what we discussed in a past core team meeting:

TL;DR; wait until Black 1.0, and Django uses it

• https://github.com/django/deps/blob/master/accepted/0008-black.rst
• Django has confirmed they will adopt Black (Python code formatter) once Black reaches 1.0
• https://black.readthedocs.io/en/stable/
• https://black.readthedocs.io/en/stable/installation_and_usage.html#command-line-options
• Matt’s thoughts
  • potentialy risk of distorting the git history but this has not been a major irritation (eg. renaming some folders last year)
  • list formatting is still not fully solved (ie. not as ‘smart’) and this may cuase some points of contention
  • Not against it in princible
• Bertrand
  • workflow, do we expect people to run Black from their computer?
  • Not a fan of pre-commit hooks as this means environment has to be set up correctly
• Decision - await to see what Django do for this, how their tooling is set up, how they make it easier for their contributors to use the formatter locally and also check things are formatted for Pull Requests

---

Relevant links:

• PR trialing black formatting: [WIP] Reformat whole codebase with black #5310
• Django DEP 0008, https://github.com/django/deps/blob/master/accepted/0008-black.rst
• black’s stable release plans, Non-prerelease black release psf/black#517 (comment)
• black’s stable release roadmap, https://github.com/psf/black/projects/4#card-33986064

---

For reference, we’ve also discussed using Prettier as well (for JS, SCSS, Markdown, JSON, YAML). Here I think it’s just a matter of someone putting a small proposal together (in a new issue), and then making the change – we’re all in agreement we’d love to see this happen.

[yhoiseth]

@thibaudcolas Thanks for writing this up 🙂

For reference, we’ve also discussed using Prettier as well (for JS, SCSS, Markdown, JSON, YAML). Here I think it’s just a matter of someone putting a small proposal together (in a new issue), and then making the change – we’re all in agreement we’d love to see this happen.

I can give it a go.

[ichard26]

Black contributor here, I've stumbled across this issue by chance :P FYI, it is possible ignore certain commits when calling git blame using --ignore-rev or --ignore-revs-file since Git version 2.23. So at least that part of the git history won't be ruined, although the GitHub blame UI sadly doesn't support this feature yet.

For more information:
https://github.com/psf/black#migrating-your-code-style-without-ruining-git-blame
https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revltrevgt

[thibaudcolas]

FYI for people interested in this, based on psf/black#2529. The info isn’t where I’d have expected this but the FAQ explicitly says:

[…] the first stable release, expected for January 2022

cc @Tijani-Dia who was interested in working on this.

[thibaudcolas]

Black has now made a stable release, so if anyone wants to pick this up please go ahead. I’d like us to proceed with this similarly with how we’re adding Prettier:

• One PR with the black configuration, necessary integration with our other linting, continuous integration, documentation changes (see Add Prettier configuration & documentation #7908 for Prettier)
• Another separate PR with the actual auto-formatting changes – meant to be merged right after the first, but kept separate so it’s easier to recreate as-needed to avoid merge conflicts (see Prettier reformatting #7912)
• And in addition – a clear step-by-step procedure for contributors to rebase their own PRs with black formatting (see Automatic code formatting with Prettier #6059 (comment))

---

Based on reviewing how Wagtail is set up right now, I’d expect the black setup to require:

• A pyproject.toml with the configuration. Potentially a few changes to our .editorconfig too (unsure).
• black installed via our setup.py testing_extras like other static analysis tools
• Running in CircleCI in our config.yml’s backend job like for flake8
• Adding to our Makefile’s lint target
• Updating to the latest isort with the black-compatible profile
• Potentially updating our flake8 rules to be compatible with black formatting
• Docs updates to python_guidelines.rst to mention black
• A black hook in our .pre-commit-config.yaml configuration

---

I’ll mark this as a good first issue – the steps involved are by no means simple, but this none of this requires extensive knowledge of how Wagtail works.

[thibaudcolas]

Done by Dan in #7967!