Switch to Calendar Versioning

[hjacobs]

As we need to release a new version of Connexion, I propose to switch to Calendar Versioning ("CalVer") with a format of YY.MM.MICRO (example: "19.12.0")

Rationale: the current semantic versioning has limited use and nobody knows when to switch from major version 2 to 3. We should limit breaking changes as much as possible and constantly "move forward" with versions.

I switched all my personal OSS projects to Calendar Versioning, e.g. https://github.com/hjacobs/kube-downscaler/releases or https://codeberg.org/hjacobs/kube-web-view/releases

There are a number of other Python projects also using CalVer, e.g. "pip".

[hjacobs]

@dtkav WDYT?

[dtkav]

Hey @hjacobs @jmcs - I'm a big fan of SemVer personally.

Rationale: the current semantic versioning has limited use and nobody knows when to switch from major version 2 to 3. We should limit breaking changes as much as possible and constantly "move forward" with versions.

In semantic versioning the convention would be to use minor version bumps as always backwards compatible feature additions, and then store up breaking changes up for the next major version bump. I think most users know that if they upgrade to a major version bump, it might require them to change their code (like python2 -> 3).

There are some things in connexion right now that are too loosely defined, and cannot be fixed in a backwards compatible manner.

For example:

1. Validation by content type.
   Connexion is very json-centric, and doesn't work at all with endpoints that take or return multiple content types. Some users may depend on this behavior, which means that we can't fix it without breaking them.
2. Consistent internal API between flask / aiohttp
   Being able to switch between frameworks seamlessly, and share most tests across frameworks would be a big win for usability and maintainability. It means breaking some behavior that users currently rely on in aiohttp, flask, or both. I think aiohttp support is half-baked right now, and we should either (1) make the necessary breaking changes so it can be a first-class citizen, or (2) deprecate it, and potentially add Quart as a flask-compatible path toward async support.

I don't know how breaking changes work in calendar versioning in practice, but I imagine that either:

1. we still introduce breaking changes, but they come as a surprise to the user
2. we aren't able to address these issues, and accumulate cruft forever
3. we have to maintain parallel code paths for a very long time, and make changes opt-in

I think the ability to use breaking changes every major release is an important opportunity to tighten up interfaces, fix mistakes, and even drop support for things that aren't core to the product.

Which approach would you take to introducing breaking changes in CalVer? Have you had to deal with mistakes in your other projects that are unfixable without a breaking change?

It might be that I'm overly focused on these breaking changes at the moment (that's where my head has been at) - most of the time I agree it's best to be backwards compatible.

I'll read up on CalVer conventions a bit more, and try to think through the implications for the backwards-incompatible fixes in the pipeline ( eg. #760 #1095 ).

[cognifloyd]

CalVer requires that we define our own backwards compatibility contract.

Ubuntu:

The non-deprecated parts of Twisted are backwards-compatible between each successive version, and breaking changes are done on a time basis, where one year must pass and two releases issued between the release deprecating the functionality and the removal of the functionality.

Twisted:

The non-deprecated parts of Twisted are backwards-compatible between each successive version, and breaking changes are done on a time basis, where one year must pass and two releases issued between the release deprecating the functionality and the removal of the functionality.

If the goal is to be able to move quickly, then semver does not prevent that. We don't even have to branch to preserve a "stable" branch as I requested in #1096. If we want to move fast and break things, then lets add a note in the readme that says something along the lines of:

Warning: Many new releases are coming. Pin your dependency on connexion and upgrade with care. We need to make major changes to finish harmonizing the APIs between Flask and AioHttp so that we can add other web frameworks as well. We will use the major version in semantic versioning to indicate when backwards compatible changes have occurred, but we are not maintaining any separate "stable" branches, and we are not backporting any fixes. We might revisit this once the new APIs have stabilized. Until then, expect more frequent major releases and pin your connexion dependency!

I do not like CalVer because it makes it very difficult for me to figure out when the backwards compatible change happened for whatever feature I'm interested in. So, let's just declare that v3 is the next version and start merging lots of awesome changes.

[dtkav]

hey @hjacobs - any further thoughts on this?
Do you still want to move forward with CalVer? What kind of breaking-changes policy are you imagining?

[hjacobs]

There seems to be no support for Calendar Versioning, so I won't push for this right now.