Clarify the version situation

[joseluis]

The situation

At the moment this library is in a complicated situation in regard to its version number.

It is currently not following semver, but the version is tied to the one the notcurses C library, as an indication of the API that is supposed to be compatible with. Any breaking changes that this library makes outside of the ones from the notcurses C lib API are not reflected anywhere in the version number. This is not ideal.

For example, some methods need to be declared unsafe in #12, and this doesn't have anything with the notcurses C lib.

I found some discusions regarding the problem of using semver for wrappers/binding libs:

• https://stackoverflow.com/questions/16418183/what-are-the-best-practices-to-do-semver-semantic-versioning-of-a-wrapper-libr
• Version of language bindings, api wrappers, etc semver/semver#352

Several thoughts:

• It makes most sense to have a semver version number for the development of this library, independently of any other library.
• The release of notcurses 3.0 is near. We could upgrade to 3.0 in sync with it and at the same time we adopt semver. The problem is if we keep the rapid development and iteration cycle of the bindings it would mean increasing the major version number very often.
• Ideally we should be in a major 0 version right now (Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.) (semver.md)
• I'd really like to be able to evolve API of the Rust bindings until I feel it's stable enough, (I don't like to rush to 1.0)
• Maybe we could treat the current version 2.X as development version. Or maybe even upgrade to 3.X and treat that one as the develoment version, signaling the change by bumping. And keep upgrading the version number from then on, detached from the version number increases of the notcurses C lib, as if it where a 0.X version (and indicate that in the docs). I like this option the most.
• The compatibility with which notcurses C lib specific version should also be clearly indicated in the docs.

[dankamongmen]

how can i assist here, aside from moving to semantic versioning myself (which i hope to do with 3.0.0 going forward)?

[joseluis]

thanks mate! that's great.

Well any thoughts you want to share on this issue please do.

Right now I'm tending towards moving to semver (custom dev version) which is exactly the same as semver with the addition of declaring version 3.x as a development version equivalent version 0.x in regards to the upgrade rules and such.

[dankamongmen]

that sounds like the right thing to me. i'd prefer that the actual version number not get reset, as it would mean introducing an epoch in the packaging versions, which requires going on one's hands and knees before debian-devel.

[joseluis]

that sounds like the right thing to me.

good to know

i'd prefer that the actual version number not get reset, as it would mean introducing an epoch in the packaging versions, which requires going on one's hands and knees before debian-devel.

yeah, if it comes to that I think it would be better to rename the library instead, otherwise it would be the most confusing thing ever.