[Request] Using semantic versioning

[prince-chrismc]

Currently the version is a little off the beaten path. It would be wonderful if the next big release moved to https://semver.org/ which is more preferable for tracking.

I would suggest just dropping the leading 0 :)

[eao197]

I have to explain why I avoid using SemVer for numbering versions of a library. Personally, I prefer a scheme like that:

generation.major.minor[.patch]

where generation and major means the level of incompatibility.

Generation

If generation differs that means that two versions of the library are totally incompatible. And that has several more than serious consequences.

The first. It allows using of several versions of the same library in one project. Just imagine that we have restinio-1.0.0 with the top-level namespace named restinio and restinio-2.0.0 with the top-level namespace restinio_2. We can make #include <restinio/all.hpp> and #include <restinio_2/all.hpp> inside just one .cpp-file. And even run several entry points built on different versions of RESTinio on the same Asio's event loop.

The second. Once you switch from an older version of the library to a new one, it would be completely impossible to switch back. So the upgrading to the version with greater generation value is a one-way path.

Major

If major differs that means that there are some incompatibilities like renaming or removing of some API or changes in the list of dependencies. For example, in RESTinio-0.7 request_handling_status_t can be changed from enum to some kind of variant, but the use of request_handling_status_t will be the same.

The increment of major means that you have to review your usage of the library, and maybe make some changes in your code. But usually, you have big chances to support several versions with the same generation value but different major values (via #if/#else/#endif or typedefs, or some helper facades/bridges). And that allows you to downgrade to an older version back if it's needed. See here for an example:

restinio/dev/sample/async_handling_with_sobjectizer/main.cpp

Lines 7 to 31 in 0052518

	#if !defined(SO_5_VERSION) || SO_5_VERSION < SO_5_VERSION_MAKE(6ull, 0ull, 0ull)
	decltype(auto) from_all()
	{
	return so_5::from_all();
	}
	#else
	decltype(auto) from_all()
	{
	return so_5::from_all().handle_all();
	}
	#endif
	#if !defined(SO_5_VERSION) || SO_5_VERSION < SO_5_VERSION_MAKE(7ull, 0ull, 0ull)
	template< typename Handler >
	decltype(auto) read_case( so_5::mchain_t chain, Handler && handler )
	{
	return so_5::case_( std::move(chain), std::forward<Handler>(handler) );
	}
	#else
	template< typename Handler >
	decltype(auto) read_case( so_5::mchain_t chain, Handler && handler )
	{
	return so_5::receive_case( std::move(chain), std::forward<Handler>(handler) );
	}
	#endif

Minor

The increment of minor number means the addition of some new functionality with saving the compatibility with previous versions (usually at source code level).

You can upgrade to a version with a higher minor number just by recompiling your code. And, if you don't use any new feature, you can downgrade back easily.

Patch

The increment of patch means just bug-fixing. It doesn't affect the feature list. There is 100% compatibility at the source code level.

---

Maybe it's just my limited experience, but I think that this versioning scheme is more suitable for libraries. Especially for libraries with a long lifetime. RESTinio is still a young project, but I saw the benefits of that scheme in other projects (like SObjectizer that evolves for 18 years).

The classical SemVer suits application (not library) development much better. So I think that SemVer is more appropriate for tools like grep or nginx than to libraries like RESTinio.

But it's just my opinion. If your suggestion gets a big number of votes we'll switch to SemVer after the release of restinio-1.0.0 :)