Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Guard users against upcoming Black incompatibilities #382

Closed
3 tasks done
akaihola opened this issue Aug 28, 2022 · 3 comments · Fixed by #430
Closed
3 tasks done

Guard users against upcoming Black incompatibilities #382

akaihola opened this issue Aug 28, 2022 · 3 comments · Fixed by #430
Assignees
Labels
CI documentation Improvements or additions to documentation
Milestone

Comments

@akaihola
Copy link
Owner

akaihola commented Aug 28, 2022

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)

@akaihola akaihola self-assigned this Aug 28, 2022
@akaihola akaihola added documentation Improvements or additions to documentation CI labels Aug 28, 2022
@akaihola akaihola added this to the 1.5.1 milestone Aug 28, 2022
@akaihola akaihola modified the milestones: 1.5.1, 1.6.0 Sep 13, 2022
@akaihola akaihola modified the milestones: 1.6.0, 1.6.1 Dec 19, 2022
@MatthijsBurgh MatthijsBurgh changed the title Guard users against upcoming Black incompatibliities Guard users against upcoming Black incompatibilities Dec 26, 2022
@MatthijsBurgh
Copy link
Collaborator

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

@akaihola
Copy link
Owner Author

akaihola commented Dec 26, 2022

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
Copy link
Owner Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CI documentation Improvements or additions to documentation
Projects
None yet
2 participants