Have a deprecation policy

[untitaker]

When sanic was using semver, it was very clear which version is bumped for API-breaking changes. With the adoption of calver, this is not clear at all.

At Sentry we maintain code that hooks into Sanic's API to report uncaught exceptions. If Sanic was still following semver, we would have a test matrix of Sanic versions 0.8, 0.9, 1.x, 2.x and so on. Which version ranges make sense now?

Twisted uses calver but also has a incredibly extensive deprecation policy which solves this problem. Sanic used to come with the implicit guarantees of semver, but now has nothing.

[sjsadowski]

Releases tagged LTS will not include breaking changes. Our expected cadence for those is annually with the .12 releases. We expect to include security and maintenance fixes. Any releases not identified as LTS may include breaking changes.

[untitaker]

FWIW this policy will likely become a headache for Sentry supporting Sanic. We are currently supporting 0.8, 18, and 19 and just experienced CI breakage because of a change in supported Python versions.

As far as I understand your versioning scheme implies that version 18.* is the latest stable release, and 19.* is essentially a beta release. Which means Sentry should support only 0.8.* and 18.* as 19.* is still too much in development.

That's fine, but no tooling expects this. pip install sanic installs the "beta" release, and this reflects in the numbers we get in Sentry, as version 19 seems to be way more popular than version 18. So practically we're forced to support a version that is still very much in development.

[ahopkins]

I will not speak for everyone, but I do understand your point and appreciate you bringing this to us. We are trying to take a "build fast, run fast" attitude, which also means that we are trying to be reactive to users as features and bugs come in. Which means with a regular release cycle, and an LTS, we can give developers an expectation.

Now, using the terms "beta" and "stable" are somewhat arbitrary. The whole project is still classified as "beta" in PyPI. If your usage numbers are showing a bent towards v19 releases, then great. That doesn't make version 18 any less "in development" than v19. I for one use the 18.12LTS in production for work.And will wait to upgrade to 19.12 in the beginning of 2020. Knowing that a particular version will be supported with security or other major bug fixes for two years isn't a statement of its "betaness", but if it's assurance that you will not be required to upgrade.

Neither semver nor calver are perfect systems. They have advantages and disadvantages. This change was a positive (from our perspective) because it gives people more clarity and transparency when making a decision on which version to use. Indeed, I would argue it is much more predictable than the previous "zero-ver" that it was on, and that projects like Flask just were able to kick.

With that said, v19.6 does have a new feature (ASGI support) that we are explicitly calling out as a beta feature. That is to say that running Sanic over ASGI may change if needed. However, that will not alter the front facing API. The LTS is there for precisely this reason. You probably are right that we need a better way to document the practices. Indeed I am hoping to have a brand new website with details like this out by the 19.12LTS.

If you have any other thoughts or critiques I for one would be happy to hear your thoughts. Again, thank you for bringing this up.

[untitaker]

19.6's breakage was not in terms of API, but in terms of supported Python versions. The labels "beta" and "stable" are not arbitrary, they are just relative. Yes, sanic as a project is considered beta, but 18 is still considered more stable than 19. In any case, if I am running my sanic v19 app on Python 3.5, updating Sanic will break my app. This was an intentional change, while the same happening with version 18 would probably be considered a bug.

Indeed, I would argue it is much more predictable than the previous "zero-ver" that it was on, and that projects like Flask just were able to kick.

From my perspective (ex-Flask maintainer) Flask has had a more predictable deprecation policy than Sanic since way before it became 1.0. A widely adopted convention for pre-1.0 versions in semver is to deprecate things in 0.*.0-versions only (and post-1.0 of course only in *.0.0), and that's what we did.

npm and cargo, two package managers with some knowledge of semver, pin such versions correctly (e.g. cargo add sanic would pin to 0.8.* or 19.*). Of course those ecosystems are a bit different because they make stronger assumptions than pip about how version numbers work.

Really, one thing i care about right now is: If I start my project in Sanic, which version should I use? Again, I would assume pip install sanic gives me the right version, and even if you document that it does not work that way I would still be surprised as a user.

In any case I will no longer have tests for sanic 19 in the Sentry SDK's CI until 19.12 comes out.

[ahopkins]

https://sanicframework.org/en/guide/project/policies.html#policies