cattrs

cattrs copied to clipboard

I am currently in the process of upgrading dependencies of our internal libraries and tooling. I noticed the new versioning scheme and have a few questions.

The changelog simply states "cattrs now uses the CalVer versioning convention." It however makes no mention of the reasoning behind this change nor any of the implications for someone unfamiliar to this versioning scheme.

I have read through the latest changelog for 22.2.0 which mentions the following article: https://iscinumpy.dev/post/bound-version-constraints/ I have also read through https://calver.org/ in hopes to understand this change, but some concerns remain unanswered.

• How are backwards-incompatible changes communicated? Do we have to assume that every new release might potentially incur breaking changes? This is something that SemVer communicates really well, when used correctly.
• Will cattrs versions receive maintenance updates? If the current version is 21.3.0 and an important bug is found dating back to 22.1.0, gets fixed in main, can we expect a 22.1.1 release or will we be expected to upgrade to the latest version?

Taking some points from Henry Schreiner's blog post into consideration brings up a few concerns, primarily when it comes to his point of applications vs libraries. Looking at CalVer's notable projects, most of them are what I would consider applications, of which "I want the latest" is usually the go-to choice for many users. I would also argue that the noted libraries also fall well under the category of "I want the latest".

His blog post's Python is not JavaScript section worries me, as we have a few different packages that currently have different major-compatible specifiers (~=1.y.z)

Currently, in order to upgrade, we have to parse the entire changelog looking for certain keywords ("removed", "renamed", etc.) The best example of this being the following change in 22.2.0:

cattrs.Converter has been renamed to cattrs.BaseConverter, and cattrs.GenConverter to cattrs.Converter.

If I was for example updating from 1.7.0 to a hypothetical 23.4.0, I would have to rely on reading every single change from 1.7.0 to current all while keeping an eye out for these breaking changes. Reading through the changelogs and missing the renaming of cattrs.Converter -> cattrs.BaseConverter and cattrs.GenConverter taking over the cattrs.Converter symbol could have been a very easy mistake to make. Our organization is not all that concerned about always having the "latest" version of cattrs in the "we want the shiniest new toy, all the time" mentality but we do have to keep up with the latest Python version due to Python versions' end-of-life.

I am not advocating for a change back to semantic versioning as it's too late for that and I understand the desire to stay on track with attrs' versioning scheme. I would instead like to suggest some additional documentation regarding this project's particular use of this new versioning scheme including the motivation behind the change. I feel that this is somewhat essential for users not closely tied to the project's development, such as what this change entails and what to expect going forward, especially for those of us less familiar with CalVer

I would also like to propose separating and highlighting important changes in the changelog under verbose sub-headers, such as "Important" or "Notable changes, "Breaking changes" and so on in order to make the upgrade path easier.

Thank you for reading. I hope that this does not come off as negative or aggressive as that is far from being my intent. I simply seek to ensure that I and everyone else can be prepared to maintain our systems and usage of this library over the coming years.

I would ask that you start by reading https://hynek.me/articles/semver-will-not-save-you/.

I can see your point about communicating breaking changes better, but like the article states, every change will be breaking for someone.

Howdy,

I'm about to merge in an explicit backwards compatibility policy.

This should answer some of your questions, but to reiterate:

• we aim to avoid major changes that would necessitate a v2-style breakage. I think this is achievable in practice.
• each major version may incur minor breaking changes; these are (and will continue to be) called out prominently at the start of each version's changelog alongside applicable remedies
• we support only the latest pypi version (at this time, this is 23.2.x)
• certain APIs may be marked as provisional (currently there are no such APIs, but there might be in the future), these do not guarantee stability

I hope this answers your questions. Let me know if you have any additional ones and I can tweak the docs.