Semantic Versions coming soon

As an old warhorse, I’m struggling to keep up with the explosion in excellent tools available to ply this trade. Platform IO is a great example. It has imposed an order to version control that precludes a lot of potential problems with the fast pace at which all of this stuff is developed. One of the foundations of success for that is semantic Versioning

To that end I’m looking to adopt that version scheme for IoTaWatt. All of the dependency files that are used by IoTaWatt conform to this approach, and it makes sense as an open project that the versions adhere to this scheme as well.

A key part of moving to Semantic Versioning is the need to more formally publish the API, as the version numbering rules are somewhat driven by the effects of changes on the API. IoTaWatt as a system has both a REST API and HTML/Javascript API (that uses the REST APIs).

This is probably going to take awhile, but I think it will really help the project going forward. Hopefully, I’ll have a basic website up soon and plan to incorporate a “read the docs” subdomain with this information. That will supplant the current WiKi on github and should allow for documenting multiple versions.

To make for a smooth transition, I plan to bump the “major” (highest order) digit for the first release, so probably it will be 3.0.0 and take it from there.

If I can give a suggestion is to use to have a special usage of the PATCH number.
All even numbers of PATCH are strictly used for releases.
All odd numbers of PATCH are used on the branches.

Example:

  • branch version 3.0.1 development
  • change version to 3.0.2 for release creation and create release
  • change immediately version to 3.0.3 on branch and restart development

This is helpful to the people that are making development, for example you would immediately know if the version you have on the device is one released, therefore you would know that it is clearly identified code.
For example I assume that you are testing locally before to make a commit, what is the version of this compiled code ? The same as the previous/next release?

Semantic versioning has a provision for intermediate versions that involves a suffix to the major.minor.patch scheme.