Black adoption comments

[kissgyorgy]

Hi!

We held a meeting last week to discuss introducing Black in one of our product, and these was the main pain-points for the team. I thought it might be helpful to get a little bit insight. We plan to use it on two repositories, about 150k Loc in total. It's not a problem report, you can close it right away if you think so, but I though it might worth an open discussion. Or we might make a new concrete issue you are willing to accept or solve, or maybe there is one or two which could be mentioned in the documentation.

• How we deploy it? We have different versions of Ubuntu we have to support and it's not trivial to install for example to Ubuntu Xenial because of 3.6-only codebase. Somebody mentioned it would not be easy to make a pull request about 3.5 support because f-strings are all over the place. (We will probably use the deadsnakes PPA.)
• The quotation mark usage is terrible.

I think these two are seriously hurting Black adoption, because I read/hear these complaints all over the place (Twitter, HN, developers forum and now in our company). It would be still not too late to change these, because it is still pre 1.0. The adoption thing could be solved by ubuntu packages and for xenial, the 3.6 interpreter could be packaged with something like dh-virtualenv. Would you accept such a PR in this repo?

We just had to talk about these, not necessarily problems:

• How do we install it? Do we install from salt, globally with python -m pip or in a virtualenv? We agreed in a virtualenv, because then you don't have to redeploy Jenkins slaves or other test machines when a new Black version is released.
• When do we run it? Should it be introduced in a git pre-commit hook, should CI run it, should CI only test it? We agreed that CI will only call --check, and everybody will format themselves.
• How gradually will we introduce it? Do we format it once and be done with it and from that point there is just Black, or do we introduce it for changed files. The gradual introduction doesn't seem viable at all.
• There will be people who will not like the formatting style at all after we committed the initial format changes. That can be a problem. I said that EVERYBODY has something which will hate about it, but we don't have to argue or think about formatting anymore. I read the README and discussion about the style, but I feel like Black doesn't follow long-standing practices or common usage patterns.
• What about developer machines? We agreed that everybody should install and use it themselves, we don't want to force anybody to any particular workflow.
• Will we run pep8 (now pycodestyle) also in tandem? We agreed to drop it and use black instead.

[madig]

When do we run it? Should it be introduced in a git pre-commit hook, should CI run it, should CI only test it? We agreed that CI will only call --check, and everybody will format themselves. [...] What about developer machines? We agreed that everybody should install and use it themselves, we don't want to force anybody to any particular workflow.

You can run it as a pre-commit hook: https://github.com/ambv/black#version-control-integration. I run the hook on my CI, too. That way, things can't slip by.

There will be people who will not like the formatting style at all after we committed the initial format changes.

I think that's just a phase. We humans simply like what we're used to and given time, you can get used to anything :) Nowadays, my fingers start itching when I touch a code-base that hasn't been blacked.

[zsol]

Hey @kissgyorgy thanks for the thoughtful feedback.

How we deploy it? We have different versions of Ubuntu we have to support and it's not trivial to install for example to Ubuntu Xenial because of 3.6-only codebase.

Most OSes have a relatively painless way of installing a recent python version (deadsnakes is pretty viable for Ubuntu as you mentioned). I don't think this is compelling a reason enough to limit black to 3.5.

The quotation mark usage is terrible.

I disagree, but this is subjective, and it's hard to argue with no arguments :) Have you looked at the -S command line option?

When do we run it? Should it be introduced in a git pre-commit hook, should CI run it, should CI only test it? We agreed that CI will only call --check, and everybody will format themselves.

I would recommend you use a pre-commit hook of some kind, if you expect everyone to do it. Otherwise it will just get annoying for people who forget to do it (I know I do sometimes on an ad-hoc clone). Look at https://pre-commit.com/

How gradually will we introduce it? Do we format it once and be done with it and from that point there is just Black, or do we introduce it for changed files. The gradual introduction doesn't seem viable at all.

In my experience, a single commit that formats the entire repo is the least painful way for everyone by far. Having said that, opting in directory-by-directory is also definitely viable, and we're doing just that for some repos in my company.

[JelleZijlstra]

How do we install it? Do we install from salt, globally with python -m pip or in a virtualenv? We agreed in a virtualenv, because then you don't have to redeploy Jenkins slaves or other test machines when a new Black version is released.

It's actually probably better to require explicit config changes to update your Black version. New versions can and will change styling, so if your CI just always downloads the latest version, it may start failing without any changes from your side. It's safer to pin a version and update through an explicit config change when you are ready.

When do we run it? Should it be introduced in a git pre-commit hook, should CI run it, should CI only test it? We agreed that CI will only call --check, and everybody will format themselves.

I also recently introduced Black at my company. We run --check in CI and provide a local tool that runs Black directly on changed files.

There will be people who will not like the formatting style at all after we committed the initial format changes. That can be a problem. I said that EVERYBODY has something which will hate about it, but we don't have to argue or think about formatting anymore. I read the README and discussion about the style, but I feel like Black doesn't follow long-standing practices or common usage patterns.

The main argument I used for introducing Black at my company (freely adapted from Lukasz's talks) was that it would prevent developers from wasting time arguing and thinking about inconsequential things like formatting details. I actually found that people came on board with that attitude pretty quickly; we had few complaints about Black's styling.

Will we run pep8 (now pycodestyle) also in tandem? We agreed to drop it and use black instead.

Black fixes much but not all of what linters like pycodestyle complain about. For example, looking at the README at https://github.com/PyCQA/pycodestyle, Black won't fix W601 .has_key() is deprecated, use 'in' or E401 multiple imports on one line. If you care about such issues, it may still be useful to run a separate linter.