Skip to content

HASS.Agent's version system

Warning

You must read and understand this entire page if you want to be able to develop any part of HASS.Agent. It helps you to understand the versioning and how to understand different versions of HASS.Agent

Overview

HASS.Agent is based on one version system

All parts off HASS.Agent use semver to keep track of their versions.

Summary of SemVer

This is a general summary of SemVer and how you will indicate different versions throughout development. You may be tempted to skip this if you know SemVer but don't, because how we indicate dev builds and betas is different to others.

Stable release versions

All release version numbers of HASS.Agent look like this: <major>.<minor>.<patch>
An example of a released version number: 1.5.4

Major

The major version number is rarely changed, if you are reading this documentation you will most likely never have to change this. But for your information it is only changed when breaking API updates are added. So version 2.*.* client, is not backwards compatible with version 2.*.*. This also means that all versions of 1.*.* will be backwards compatible, there may be small warnings or missing features but all previous API calls and features work as intended. Basically this version number only needs to be incremented when no backwards compatability is added. This also forces the dev team to not release backwards compatible updates very often.

Example
  • Version 1.4.2 of the client does have backwards compatibility with version 1.8.3
  • Version 2.3.2 of the lient does not have backwards compatibility with version 1.8.3

Minor

The minor version number is to be incremented whenever new features are added in a backwards compatible way. More than one feature can be added per version number, however they all have to have backwards compatibility.

Example
  • Version 1.4.1 of the client will have less features than 1.5.0
  • Version 1.6.0 of the client will have more features than 1.5.0

Note that in both of these examples the versions are backwards compatible.

Patch

The patch version number is to be incremented whenever bug fixes(patches) are released in a backwards compatible way. All bug fixes are to be released in a backwards compatible way anyway, so basically everytime a patch is released, this number will be incremented. The important thing to note about the patch version number is that no new features can be added.

Example
  • Version 1.3.0 of the client will have more bugs than 1.3.1 of the client
  • Version 1.5.6 of the client will have more patches and therefore less bugs, than 1.5.2 of the client

No new features are added between the versions in these examples. Only bug fixes and patches are added.

Beta developmental versions

During the development of a new version of the HASS.Agent client beta versions of the code will exist. These versions will be denoted like this: <major>.<minor>.<patch>-beta.<beta-version> You will notice the only difference is the addition of the -beta flag and the fourth version number <beta-version> The first beta version of the example upcoming 1.5.3 release would look like this: 1.5.3-beta.0

Beta version

The beta version number is to be incremented whenever a new beta version of the code is built or released for testing.

Example

The current stable version is 2.5.4 and the dev team is working on a new feature

The beta version during the first development update should be 2.6.0-beta.0

Everytime a new development update is added to this feature the last number should be incremented.

The dev team has now finished working on this feature

The stable version for release should be 2.6.0

The dev team has found bugs and is working on a hotfix. They are in devlopment of the second hotfix right now.

The current beta version should be 2.6.1-beta.1 (1)

They have now completed this hotfix

The stable release version should be 2.6.1

  1. We use 1 for the <beta-version> here, because hotfix 1 was .0 and hotfix 2 was .1

Other info

Resetting numbers

Whenever a "parent" version number is incremented the "children" numbers must be rest to zero.

Example
  • If the current version is 1.5.6 and a new backwards compatible feature is being added the new version will be 1.6.0
  • If the current version is 1.5.6 and a new backwards incompatible feature is being added the new version will be 2.0.0

Documentation

The documentation operates on version of just <major>.<minor> This will still match the client because no major documentation change will happen during a patch of the HASS.Agent client.

The other difference between this version system and the client's version system is that beta version attributes will not exist. In the documentation if the upcoming release is going to be 1.5.0 and the current beta version is 1.5.0-beta.3 then the docs will have 1.5 with the label/attribute beta.

Relationship between the client and the integration

Both the client and the integration are going to be using SemVer, however it will not be the same version. Instead when you checkout the installation for HASS.Agent it will tell you what version of the integration is required. The other thing is that most of the integration's development will be backwards compatible and not move up from version 2.