#️⃣ Guideline: Semantic Versioning

[almostearthling]

Starting with version 2.0.0, When uses semantic versioning in a more strict way. In particular, the convention is that, given a version number of the form X.Y.Z, the parts have the following meaning:

• X (major) will increase only when breaking changes are introduced, which may cause the new version to be incompatible with the previous one,
• Y (minor) will increase every time a new feature is added, that nevertheless adds up without introducing incompatibilities,
• Z (patch level) will be increased at every bug fix, when such fix does not cause the new version to be incompatible with the previous one.

Also a suffix of -alpha or -beta (possibly followed by a dot and an increasing number) will indicate respectively unstable and stable pre-releases that will eventually be released in production state by dropping the suffix.

This means, for example, that:

• version 1.32.4 is three bug fixes behind 1.32.7, and has more features released than 1.31.15
• version 1.33.5-alpha.3 and 1.33.5-beta, have more features than the releases above, but are both pre-releases of which the former has to be considered unstable and has been updated three times after its first appearance -- which was dubbed just 1.33.5-alpha
• version 1.33.5 is the production grade release that follows successful tests of the 1.33.5-beta series.

Note

Both the minor version and the patch level are reset to zero every time the major version and the minor version respectively increase.

In the documentation, and elsewhere in discussions, issues, and other sections of the repository, expressions like "at least version X.Y.Z", "above version X.Y.Z", and so on, follow the ordering rules specified in the semantic versioning web site.

[almostearthling]

📢 Additional Notes

For the sake of of versioning, there are some kinds of modification that could be interpreted as breaking changes but that, in the development of When, will be considered either fixes or enhancements depending on their nature: this comment and the list below will be updated with time when changes of this kind show up:

1. changes that imply reopening the form that configure an item and then save the configuration in order to recover from a problem (always fix)
2. changes that affect the configuration file in a way that requires the use of the --fix-config tool to upgrade the configuration file without other action (fix or enhancement)

Fixes and amendments in the documentation, when provided without changes in the application, will never imply a version change.