In the past 6 months for a few select private repositories, edX has use the
black autoformatter in an attempt to keep our code style consistent, minimize style discussions, and get back the time we spend fixing style linting errors on our PRs.
On my low priority backlog, I now have a ticket for converting an Open edX repo (Credentials) to
black as well. Prior to doing so (and possibly shepherding in an era of autoformatting all of our repos), I figured I’d gauge how the community feels about this. First, a couple of the "why"s and "what"s.
Honestly, because it’s a service my team now owns, and we’ve had a good experience using it in the other private repos that my team also owns. More importantly however, is that Credentials is both a smaller repo and one with less community contributions, so it’s an easier “first” where we can gather input while minimally disrupting things.
Our services are now running on Python 3.8 (from 3.5) and thus we no longer have the mismatch of running code on a version that the formatter doesn’t support (3.6+). We’ve also been talking about it for a long time, and it’s become less of an “if” and more of a “when”. The “when” is “now”-ish.
Why add an autoformatter?
Mentioned this above and I’m sure there’s plenty more on
black's website, but the short version is that we want consistent looking code without wasting brain time thinking about formatting.
What will this look like?
For our existing repos we have new Makefile commands called
black --check .respectively. The
format_checkcommand then gets ran inside the existing quality checks we have in the repo. You can either run
make formatprior to pushing your PR, or run it and re-push after you get the failed quality test because you forgot (this is what often happens in practice). I’ll copy this plan unless this thread takes me in other directions. The only configuration we have set is to make line-length 120 instead of 80. We also removed
pycodestylewhen we transitioned as they are extraneous and conflicting.
What will the first autoformat look like?
One semi-massive PR that will make most of your
git blames useless for a bit. I’ll be biting the bullet for credentials, and have my name attached to everything for a while.
blackcompares ASTs pre- and post- formatting, so this should be a safe PR regardless of the size.
black can be contentious, so I want to hear your excitement, dismay, pain points, and successes along with any thoughts you may have about how to implement it. If describing an pain point that open source development will feel from this, please include it’s severity as I’m not entirely in-the-know about how often open source would fight these pain points.
Thanks in advance!