Any advice for existing projects transitioning to black?

[max-sixty]

Does anyone have any advice for projects with a large existing codebase that are implementing black, specifically to make it easy for existing PRs to merge following adopting black?
We're planning on rolling this out in xarray in pydata/xarray#3142 and looking to ease the transition for our contributors who have outstanding PRs.

My current thoughts are to recommend these steps for existing PRs:

• Merge the commit on master prior to the black commit into your branch git merge [master-before-black-commit]. Any conflicts are real conflicts and require resolving
• Apply black . to your branch and commit
• Merge master at the black commit, resolving in favor of 'our' changes: git merge [master-at-black-commit] -X ours. You shouldn't have any merge conflicts
• Merge current master git merge master; any conflicts here are real and again require resolving

For transparency, I added a similar comment to #896 a couple of weeks ago. If you don't think this is relevant / is out of scope, feel free to close.

[max-sixty]

FYI we just committed the black changes and I've successfully tested this a couple of times.

One wrinkle - we added some manual changes on top of the black changes (i.e. within the commit). That threw off the second merge. I added a patch of those for people to apply before that second commit (pydata/xarray#3195). We should have instead done only the black changes in one commit, and then manual changes separately.

[ichard26]

If you don't think this is relevant / is out of scope, feel free to close.

Quite late, but no I don't think this is out of scope. We actually now have a "Introducing Black to your project" guide, it's woefully incomplete and needs a lot of work (it was born from a super focused documentation request so that's why it's incomplete). This feedback is lovely and if I ever get back to this, I'll see if your experience is applicable.

Thank you!