Repository navigation
Deprecation Policy. #587
Description
At this point in time we ought to have a clear warning on the docs to pin to a median version. eg. 0.8.x
Using this issue to describe what I'd like our deprecation policy to be once we hit 1.0.
- Upgrading from X to X+1 (1.0 to 2.0) never breaks any public API, but may raise warnings.
- Upgrading from X to X+2 (2.0 to 3.0) warnings esclate into errors.
- Upgrading from X to X+3 (3.0 to 4.0) code is deprecated.
The deprecation policy would apply to all publically documented code.
We'd recommend that users pin to whichever major version they're using.
(Actually pinning to X or X+1 would also be okay.)
We might initially want to mark a couple of things as provisional (eg. I very much doubt we'd have the Backend API covered by the policy, or publicly documented. Our exception heirachy might not be fully nailed down.)
Activity
florimondmanca commentedon Dec 3, 2019
Interesting!
So I assume « escalate into errors » still means that we track the code path and raise an appropriate exception/error message, right?
What are the pros of having a « pad major » between breaking changes? Have you seen it help adoption/upgrades compared to strict semver?
StephenBrown2 commentedon Dec 3, 2019
I was thinking it would follow marking things with PendingDeprecationWarning and then DeprecationWarning, but those aren't errors.
Could also borrow from the deprecation library for an easy decorator.
lovelydinosaur commentedon Dec 3, 2019
Good call, yes.
plizonczyk commentedon Dec 3, 2019
Not sure if it's the right place, but 0.8 has brought fairly breaking change with removal of AsyncClient, without any prior warning. CHANGELOG.md hasn't been updated neither. The reason I'm bringing it up here is that maybe it's worth to enforce deprecation warnings before v1.0 (unless it's the next version)?
florimondmanca commentedon Dec 4, 2019
Thanks for raising this @plizonczyk :-)
Ah, correct. @tomchristie Seems only the package was pushed to PyPI, without an extra
Release 0.8commit + tag?We most likely won't be breaking things as hard as with 0.8 again pre-1.0, but I hear that the change might have come across as a bit brutal, and our communication could have been more proactive generally (e.g. strongly encouraging users to pin the dependency to the current minor version when installing). But my position on this is that we shouldn't commit to too much deprecation ceremony while in 0.x.
@tomchristie I notice the README has dropped the "This project is still alpha" note; should we bring it back, or perhaps in a "beta" form?
lovelydinosaur commentedon Dec 4, 2019
@plizonczyk - Yes. That was unneccessarily blunt, apologies. I've started by updating the README, like so...
Note: HTTPX should still be considered in alpha. We'd love early users and feedback,
but would strongly recommend pinning your dependencies to the latest median
release, so that you're able to properly review API changes between package
updates. Currently you should be using
http==0.8.*.In particular, the 0.8 release switched HTTPX into focusing exclusively on
providing an async client, in order to move the project forward, and help
us change our approach to providing sync+async support. If
you have been using the sync client, you may want to pin to
http==0.7.*,and wait until our sync client is reintroduced.
We should certainly consider that.
lovelydinosaur commentedon Dec 4, 2019
See also #590
lig commentedon Apr 25, 2020
The lack of the policy at the moment causes things like that authlib/authlib#208
Despite the "alpha" status, the project has some spread already. Breaking changes like that should change
ynumber inx.y.z. Otherwise, a good project could gain a critical mass of negative feelings in minds before it makes it to 1.0. This has some potential to become disastrous for the project reputation which could be sadly irreversible.lovelydinosaur commentedon Apr 25, 2020
They are. We're pretty clear about following that, but there happened to be a packaging issue in 0.12.0 which had inadvertently left the
.content_streamsmodule in place.lovelydinosaur commentedon Apr 25, 2020
Incidentally ContentStreams has never been a publicly documented API, we’re just being tighter now on ensuring that users aren’t inadvertently relying on private implementation details.
Would be happy to spend some time helping resolve any issues with dependent libs if that’s helpful?
lig commentedon Apr 25, 2020
@tomchristie Thank you for the honesty!
I would humbly ask to look into authlib issues with 0.12.1 as of this forces all users of it to stick with 0.12.0 at the moment.
Keep the good work!
Lawouach commentedon May 25, 2020
Hi all,
Just chiming in because I'm not certain how to help progressing this one. This is a bit of an issue indeed. Not sure if the work is better carried here or on authlib for that one, but the fact we have tto pin httpx for authlib is worrying (from a security perspective, I dislike waiting too long before updating for instance).
Thanks all :)
cc @lepture
lovelydinosaur commentedon May 25, 2020
You shouldn't really have to pin
httpxthere - the latest version of authlib no longer uses private API from httpx, and so will be 0.13.x compatible and almost certainly 1.0+ compatible.I would still recommend pinning to median releases such as 0.13.x, since it'll give you an extra level of confidence.
Lawouach commentedon May 25, 2020
Oh that is awesome news. I think I got confused by the last message I saw on authlib on that issue. Thanks Tom!
lovelydinosaur commentedon Aug 7, 2020
Closing this off, since I don't think there's anything much more to say here.
We've got a very clear "pin dependancies" note on 0.x releases, and our 1.0 deprecation policy will either be SEMVER, or something more constrained that SEMVER (Eg. 1.x -> 2.x won't introduce API breakages, but may introduce API deprecations).
In any case, I'm hoping we won't need to think about it for a very long time, since we've spent a vast amount of energy nailing down the API pre-1.0.
Once we hit 1.0 we should mention that we abide by SEMVER in the CHANGELOG.
If we ever have a reason for a 2.x we can figure if we want to do something even more gradual and gentle than SEMVER at that point.