Transitioning towards autoformatting

Development
1

Hello all,

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.

Why

  1. Why Credentials?
    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.

  2. Why now?
    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.

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

  1. What will this look like?
    For our existing repos we have new Makefile commands called format and format_check which run black . and black --check . respectively. The format_check command then gets ran inside the existing quality checks we have in the repo. You can either run make format prior 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 pep8, pycodestyle when we transitioned as they are extraneous and conflicting.

  2. 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. black compares ASTs pre- and post- formatting, so this should be a safe PR regardless of the size.

I know 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!

Matt Tuchfarber

10 Likes
2

We’ve been using black formatting for some time now at MIT Open Learning and it’s all been for the good.

3

We also have a draft OEP covering autoformatting: https://github.com/edx/open-edx-proposals/pull/107