Guard users against upcoming Black incompatibilities

[akaihola]

The process for allowing Darker users to auto-update Black but still guard them against Darker/Black incompatibilities is:

1. The test-future.yml workflow regularly tests Darker against the current main HEAD of Black
2. Make a patch version release as soon as that workflow notifies about an upcoming incompatibility in Black. If that e.g. happened today, we'd release Darker 1.4.3 with a upper limit for the version of the Black dependency to the newest version known to work.
3. Then, after we've fixed the incompatibility, make a new patch version with the fix and the upper version limit removed.

This way anyone specifying darker~=1.4 for their project, Darker would automatically update to 1.4.3 and prevent Black from updating to an incompatible version before we've released a fixed Darker 1.4.4 or 1.5.0.

• Document darker~=x.y as the recommended way to depend on Darker
• Update the test-future.yml workflow to point to the guidelines in this issue in case of a failure
• Explain this process in the documentation

Originally posted by @akaihola in #334 (reply in thread)

[MatthijsBurgh]

@akaihola with a point release, you mean a patch version bump, aren't you?

[akaihola]

with a point release, you mean a patch version bump

Yes, I should probably change the terminology. I guess "point release" can refer to either a minor or patch version bump. Thanks!

I updated the README, fixing the terminology, and actually moved the long explanation to its own section at the end, along with a couple of example scenarios.

[akaihola]

README now explains:

---

Guarding against Black compatibility breakage

Darker accesses some Black internals which don't belong to its public API. Darker is thus subject to becoming incompatible with future versions of Black.

To protect users against such breakage, we test Darker daily against the Black main branch and strive to proactively fix any potential incompatibilities through this process. If a commit to Black main branch introduces an incompatibility with Darker, we will release a first patch version for Darker that prevents upgrading Black and a second patch version that fixes the incompatibility. A hypothetical example:

1. Darker 9.0.0; Black 35.12.0 -> OK
2. Darker 9.0.0; Black main (after 35.12.0) -> ERROR on CI test-future workflow
3. Darker 9.0.1 released, with constraint Black<=35.12.0 -> OK
4. Black 36.1.0 released, but Darker 9.0.1 prevents upgrade; Black 35.12.0 -> OK
5. Darker 9.0.2 released with a compatibility fix, constraint removed; Black 36.1.0 -> OK

If a Black release introduces an incompatibility before the second Darker patch version that fixes it, the first Darker patch version will downgrade Black to the latest compatible version:

1. Darker 9.0.0; Black 35.12.0 -> OK
2. Darker 9.0.0; Black 36.1.0 -> ERROR
3. Darker 9.0.1, constraint Black<=35.12.0; downgrades to Black 35.12.0 -> OK
4. Darker 9.0.2 released with a compatibility fix, constraint removed; Black 36.1.0 -> OK

To be completely safe, you can pin both Darker and Black to known good versions, but this may prevent you from receiving improvements in Black.

It is recommended to use the '~=' "compatible release" version specifier for Darker to ensure you have the latest version before the next major release that may cause compatibility issues.

See issue #382 and PR #430 for more information.