Upper limit for required Black version?

[akaihola]

In conda-forge/darker-feedstock#10, we were discussing with @martinRenou whether to define a maximum version for the Black dependency in the Conda package for Darker.

@martinRenou wrote:

It's usually better to add an upper constraint to the next breaking release, to prevent bad surprises. So in this case we should probably change that upper limit to 22.0? Anyway, it's also good keep it in sync with the pypi constraints I guess. Up to you 😊

The thing is, Black doesn't have a stable Python API (see psf/black#779) so while we can count on its output to stay stable throughout a calendar year due to Black's new stability policy, we have no guarantees about the internal Python functions and classes we're using.

So if we say Black<23, the Python API might still break in 22.x.

And even if we omit the upper limit, Black 25.5 might still work just fine with today's Darker, even if it gives slightly different formatting results. And that change the users can protect against by specifying Black<23 in their own project dependencies or pipelines.

Maybe it makes most sense to document that

• We can't guarantee that the current Darker version will work with any given future Black version (even the next one).
• But because we don't want to prevent users from upgrading Black,
• and since we don't want to make a Darker release for each new Black release,
• there is no upper version limit for the Black dependency.
• Thus, we recommend pinning Black and only upgrading it explicitly after testing that it works with the version of Darker the user is running

How does that sound?

[martinRenou]

So if we say Black<23, the Python API might still break in 22.x

😕 that's annoying indeed.

How does that sound?

I guess it's a good plan then.

If black's Python API is not so stable, it could also be worth adding a Github action CI job that tests darker against the black dev branch, in order to catch API changes early, before users get a broken setup.

[akaihola]

CI job that tests darker against the black dev branch

Ah, good that you reminded, we actually already have that! Here's a run of that job, and it's defined in .github/workflows/test-future.yml. This was added in #284 and discussed in #186.

I'll come up with the addition to documentation.

[martinRenou]

Great! I should have checked before commenting :)

[akaihola]

Maybe it would also be a good practice to make a point release as soon as we notice 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.

Then, after we've fixed the incompatibility, we'd make a new release 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.

[akaihola]

#382 will establish a process for guarding Darker users against incompatibilities with auto-updated Black versions, and also document recommendations to follow and explanations of how this works.