Introducing a code formatter to an existing code base with running branches

Question

We have an existing code base in Python which doesn't yet use any code formatting tool. Now we have settled on YAPF as a tool and also created its configuration file. To me it is not clear how to reformat the code base without causing havoc in further rebases.

At the moment we rebase everything onto master such that it is a linear history. Some feature branches will need to rebase. This means that all commits in the branch will have to be rebased onto a new master with different formatting. This will likely lead to a lot of merge conflicts in the application of the individual patches.

Git rebase has the option --ignore-whitespace which will likely get us pretty far. But there still may be some issues left over. We will of course try to have the least number of non-master commits around.

Is there some established way to introduce a formatting tool into an existing codebase like this?

Answer 1

A few possibilities:

1. Piecemeal, maybe in an automated fashion: check out a new branch, format a single file, commit, push and create a merge request. At this point there should be minimal interruptions to other people. You could even build in some smarts in the automation, only reformatting files unrelated to any currently ongoing work. In that case you might get away with just a handful of merge requests to reformat everything.
2. Set aside a time window for formatting all the code in one go. This is obviously the least painful for you, but could be costly depending on what others are doing.
3. Wait for a merge window to appear organically. Basically, keep polling whether there is any work in progress. If there's none, get your merge request in there and push it through as fast as possible, to minimise disruption. This might work depending on how long your pipeline takes from creating a merge request to actually merging it, and might of course not be feasible if there's always heaps of ongoing work.

Answer 2

So the situation is that any file touched by your code formatted will look very much different after it is formatted. And that will make diffs between “before” and “after” files painful.

First thing, you check that your formatting tool is consistent. I’ve seen tools that switched between two states every time it would format code! If that’s the case, throw the tool away, never let it touch your code.

Second thing, take an existing file, make a trivial change plus reformatting. Try a diff. Are you wasting lots of time? Did you find the trivial change? If you wasted lots of time, worse, if you couldn’t spot real changes, think very hard.

You might have a rule that formatting changes must not be mixed with other changes. Ever. If you want to edit files A, B and C, you first make a pull request for “reformat A, B and C using the new tool”. And when that’s reviewed , you do your actual work.

And maybe you should think what all this is good for. Does it actually benefit you? If there’s no benefit, then don’t do it. Or only if it changes adherence to a policy from 95% to 100%. And in that case, only if the 100% is actually an improvement.