Versioning strategy proposal

[gdubicki]

One of the things I don't like about ruamel.yaml is the versioning scheme that makes it impossible to safely set a version for it like ">= X, < X+1" because there were API breaking changes within the minor version update:

• 0.15.0 - significant loading and dumping API change
• 0.17.0 - removing Python 2 support, stop support for the old PyYAML functions, so a YAML() instance will need to be created.
• 0.18.0 - Python 3.5 support will be removed

I would like to propose this project to have versioning based on semantic versioning because I want users of this module to feel safe and confident that their apps will not suddenly break.

I propose to not try to keep our versioning aligned with upstream in any way - I would NOT try to have our version numbers somehow "automatically" be generated out of upstream version (like major version +1 or sth like that) and NOT promise to release each upstream release as a separate release.

What we should do is to have clear information in the changelog and GitHub release descriptions about what upstream version has been merged into our one. And each time we would merge upstream changes we should reevaluate according to semver and common sense if a given release should be upticked in the patch, minor or major version.

As the new major versions are a big pain to roll out, they should be discussed with the project community before being made to ensure that this is really necessary - perhaps they are some backward-compatible options to move forward too.

We should create pre-releases (as defined by PEP 440) and ask users to test them and report their issues. This together with automated tests should minimize the problemss like the yanked versions 0.17.0 and 0.17.1 of the upstream.

To prevent too quick jump of the major version numbers from 1 to 2, as Python 3.5 is EOL since September 2020, let's drop support for it already before ruyaml 1.0 release. Otherwise whenever upstream 0.18.0 is released - and this may happen any moment now - and we will merge it, we would like to uptick the major version to 2. This would not look great if it happens f.e. just weeks or days after 1.0 release if we promise better API stability. (Of course if 0.18.0 will also have a backward-incompatible API change that will affect Python 3.6+ users, then we would have to uptick the major version.)

(I was considering dropping Python 3.6 support as well, as it will be EOL at the end of December 2021, but it's the latest Python 3 version available under Centos/RHEL 7 - according to my knowledge - and the latter will be EOL only in June 2024 so I would personally prefer to keep Python 3.6 support for at least a few more months, until hopefully a new Python version will be at least (semi)officially released for Centos/RHEL 7.)

What do you think about this? Any objections, counterproposal, would you change some parts?

[smurfix]

Right. A production-ready software, which we'd like to think ruyaml is 😎, should not use major number zero.

[ssbarnea]

I am upgrading the GHA workflows right now to re-use the same model we use for Ansible DevTools projects. You will see that release drafter will automatically draft release notes and compute their version number based on nature of merged pull requests (labels do determine that). There is also a workflow that ensures PRs have the right labels. It will tell you what labels you should add or remove and you can do that even after a change is merged. As long we have one major change in master branch, we should see next version listed as v1.0.0.

Dropping py36 support is out of question for now, there are many users still using it and so far I did not drop it from any project. py36 is a bit of a LTS and will have to stick more than normal and likely we will switch to py38 quickly after dropping it.

As now we have a bunch of people interested about project future, it will be much easier to revive its development. I can still ensure that the CI is running.

[gdubicki]

I am upgrading the GHA workflows right now to re-use the same model we use for Ansible DevTools projects. (…) As long we have one major change in master branch, we should see next version listed as v1.0.0.

Great, thanks! But let’s release some a pre-release(s) of v1.0.0 before we go final. It would not be good to start with a false start. :)

Dropping py36 support is out of question for now (…)

Sure, scratch that.