Improper library version numbering

[ryandesign]

I'm concerned that tidy's library version numbering is not correct. Specifically, the project's major version number (e.g. 4) is being used as the library's major version number, but these are two separate and distinct concepts which need separately-managed numbers. You're also using the project's full version number (e.g. 4.9.35) as the library's minor version number; these separate concepts should also have different numbering schemes.

Take for instance your current development series, 4.9.x. As I understand it, your plan is to release project version 5.0.0 once this development series is stable. But if the library major version is the same as the project major version, doing so will increase the library's major version from 4 to 5, even though no breaking changes will presumably be introduced at that time. This will unnecessarily cause all projects linking with libtidy to need to be rebuilt.

Apple has some great documentation on library versioning.

GNU also has documentation on library versioning.

[geoffmcl]

@ryandesign, I share some of your concern about the current versioning. The major version 4 was never meant to last this long. It, together with the suffix 5 was introduced to allow a previous version of 'classic' tidy to co-exist with the developing new tidy5 version. It was supposed to be quite temporary...

There were some ideas that we would continue tidy5 separately, but I think it has now been shown that tidy can have two modes. Default html5+, but if given an older document revert to html4- mode. Proving this is feasible is one of the reasons the major 4, suffix 5 has continued so long... But I think it has been proven... so...

In general the idea is to follow Semantic Versioning, where -

1. MAJOR version change to denote incompatible API changes
2. MINOR version when functionality is added in a backwards-compatible manner
3. PATCH version on each bug fix.

The first release of tidy 5.0.0 is presently targeted for the end of this month. Then the suffix 5 will be dropped, and the shared library will be ligtidy.so.5.0.0, and soft links libtidy.so and libtidy.so.5 will be created.

Yes, this may require projects linking with libtidy to be rebuilt. This will be the first release of tidy in about 6 years...

A tag and a 5.0.0 release branch will be created. And the master branch changed to 5.1.0

There after, only the PATCH number will increase for each bug fix, and maybe some feature fixes applied giving 5.1.1, 5.1.2, ... in master... the development branch...

If a fix is significant, important, such fixes will also be pushed to the 5.0.0 branch, making it 5.0.1, 5.0.2, ... and projects linking with libtidy would not need to be rebuilt to be able to use this later library. Just pull, compile and install the later library...

When thought appropriate a next release 5.2.0 (tag and branch) created, but again projects linking with libtidy only need pull, compile and install to use this next release. And the master moved on to 5.3.0...

And so on, at least until there are incompatible API changes...

It is agreed there are many variation on versioning, and here have chosen one...

Does this sound reasonable to you and others?

[skynet]

👍 sounds good to me

[ryandesign]

Yes, this may require projects linking with libtidy to be rebuilt. This will be the first release of tidy in about 6 years...

But remember that the version of tidy from 6 years ago (20090325 is what we had in MacPorts before we switched to your fork) installed a library with a Mac OS X install_name of /opt/local/lib/libtidy-0.99.0.dylib with a compatibility and current version of 1.0.0. That already differs from what your version of tidy installs today, which has an install_name of /opt/local/lib/libtidy5.4.dylib with a compatibility version of 4.0.0 and a current version 4.9.36. So there's no need to further increase the library major version (e.g. from 4 to 5) to differentiate yourself from that old version.

In MacPorts, we have already dropped the "5" suffix from the library name, so our tidy install_name is /opt/local/lib/libtidy.4.dylib. We did not want to modify all ports that use tidy to teach them about the "5" suffix, only to have to modify them again later to remove that again.

Semver is good, but it still sounds like you're planning on keeping the library version tied to the project's release version, which isn't recommended, as I've said. There is no reason why the library's major version should increase from 4 to 5 with the release of tidy 5.0.0 if the library does not change in a backward-incompatible way between now and then¹. The library major version and the project's release version should be treated as two distinct concepts, for example by maintaining two separate variables within your build system that can be independently increased as needed.

Consider also that your project contains not only the libtidy library but also the tidy program. Consider that you might some day want to release a completely rewritten version of the tidy program with much new functionality. That might warrant a significant increase of the project's release version, but if the library has not changed in a backward-incompatible way, then it would not warrant an increase in the library's major version.

__

1. An exception would be if there has been a point during libtidy5.4's development where it did already change in a backward-incompatible way but the library's major version was not increased at that time.

[geoffmcl]

@ryandesign, sorry, I guess I did not make it clear enough. There was never supposed to be a major 4 released. And further distinguished it by adding a 5 suffux. It was just an interim, which got extended and extended and extended... It was always intended that the next release would jump all the numbers from 0.99, 1.0, etc directly to 5.0.0, and that's what will happen...

And while the API is mostly binary compatible even with 0.99, some enumeration have changed, especially related to config, thus it is necessary to rebuild any project that uses libtidy...

And this is all about the libtidy version, and that is the project version...

In essence the tidy console app is just an example of how to use libtidy, so it has no 'version'. And yes, if we did choose to re-write this console app, but not sure why, then it might begin to have it own version, and as you point out that could be different to the libtidy, aka project version.

Good to hear you have already dropped the suffix 5... I made sure that was as easy as changing one name in CMakeLists.txt... which is exactly what I will do next week on releasing 5.0.0...

[geoffmcl]

@ryandesign hope now all is agreed...

[skynet]

👍