Httpx: Deprecation Policy.

[tomchristie]

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.)

[florimondmanca]

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]

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.

[tomchristie]

Good call, yes.

[plizonczyk]

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]

Thanks for raising this @plizonczyk :-)

CHANGELOG.md hasn't been updated neither.

Ah, correct. @tomchristie Seems only the package was pushed to PyPI, without an extra Release 0.8 commit + tag?

maybe it's worth to enforce deprecation warnings before v1.0

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?

[tomchristie]

@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.

---

Is that maybe it's worth to enforce deprecation warnings before v1.0 (unless it's the next version)?

We should certainly consider that.

[tomchristie]

See also https://github.com/encode/httpx/pull/590

[lig]

The lack of the policy at the moment causes things like that https://github.com/lepture/authlib/issues/208

Despite the "alpha" status, the project has some spread already. Breaking changes like that should change y number in x.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.

[tomchristie]

Breaking changes like that should change y number in x.y.z

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_streams module in place.

[tomchristie]

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]

@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]

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

[tomchristie]

he fact we have to pin httpx for authlib is worrying

You shouldn't really have to pin httpx there - 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]

Oh that is awesome news. I think I got confused by the last message I saw on authlib on that issue. Thanks Tom!

[tomchristie]

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.