Versioning introduces breaking changes in minor updates

[nncsl]

Hi,

We went from 0.27.2 to 0.28.0 this morning which included this MR that introduced a number of breaking changes for us.

It very much seems like your versioning follows semantic versioning (at least from how fixes etc get tracked under the patch number), but it doesn't seem to be case, as in this case you would have bumped the major version, given that you introduced backwards-incompatible changes.

If you're not following semantic versioning, how should httpx's versioning be interpreted?

Thank you

[trim21]

semantic version allow adding breaking change before v1

[trim21]

My memory is currect, they do have a paragraph about this in readme, and it is removed when they prepare a pre-1.0.0 release, and didn't add it back.

https://github.com/encode/httpx/pull/1855/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5

[trim21]

As a user I think they should add it back, but since now they are preparing a v1 release again I'm not sure will they do it.

[nncsl]

So my personal opinion is that they should have delayed the above changes for the 1.0.0 release, since that's very clearly communicating breaking changes. Right now the library is in a sort of a limbo state that's both stable and also experimental, since presumably they want as much flexibility as they like, while not scaring people away by implying things are still very experimental.

I imagine if 0.28.0 is the last release before 1.0.0 they probably don't see a reason to keep the notice that people should pin their library version, but I think you're right that they should keep it until they go to 1.0.0.

[lovelydinosaur]

Agreed. We should be clear & direct about this...

The httpx package is not yet at a 1.0 SEMVER release. We currently recommend pinning your httpx dependency to 0.28, and reviewing the CHANGELOG for deprecations when upgrading.

(My assumption was that we were striking a reasonable balance with "API exists in 0.x, deprecate in 0.y, then remove in 0.z" tho evidently not cautious enough or clearly communicated.)

PRs welcome for the above text/placement, or else I'll follow up with it as soon as possible.