Release / Pre-Release strategy and versioning scheme

[Bouni]

I never really used pre-releases before but with more than just me working on this codebase it seems like a good idea to use them.

I propose that we release pre-releases at a quite high frequency in order to test things and if we think we reached a solid state we release a "real" version.

As mentioned by @kbabioch here we could use test.pypi.org for pre-releases and the real pypi for real releases.

I did a quick test over in my dummy repo with that: https://github.com/Bouni/auto-version-bump/blob/main/.github/workflows/publish-to-pypi.yml#L8-L27

We alos need to agree on a versioning scheme, @kbabioch already said he would stick to semantic versioning (1.2.3), I was in favor of the HA versioning scheme (2023.01.01) but thats just personal preference and I'm flexble with that. @BenPru, any opinion on that matter?

For pre-releases i would just add a -rc1, -rc2 and so on.

[BenPru]

any opinion on that matter?

My favor is the ha versionig scheme.

[kbabioch]

So it's 2:1 regarding the versioning scheme then :-).

I'm fine with HA versioning scheme, although I want to make sure that we don't block ourselves in the future: Are we sure that there will always be one version of this project that will be released? I guess the HA versioning scheme only works when there is one release stream. If we're confident about it, then let's go with it ;-).

[Bouni]

@kbabioch what scenarios do you have in mind that force us to maintain multiple versions?

[kbabioch]

The typical scenario are serious bug fixes and/or security issues while keeping support for older versions of the code without breaking the API too much.

For instance, let's assume the following:

• The current version of the code is integrated into the core of Home Assistant as well as used by some other applications and we have a big user base (like 100 people, etc.).
• We decide to refactor the code, add some new functionality and therefore need to break the API, e.g. we are going to refactor the Luxtronik class.
• This will require all the users to change their code, which will take some time
• Home Assistant is fast and will adopt to the new version right away
• Some other applications are not as fast and need more time to adopt to the change
• We find out about a serious bug that will write parameter that could break all heat pumps
• Now we are facing a dead-end situation
  • We can release a new version based on the latest code: Only people adopting the new code base can easily update
  • Anyone still using the old version of the code cannot upgrade, because the API changes will break the product

All of this is totally made up and will never occur in exactly this way, of course.

Still, that's why semantic versioning is used for many libraries. You can maintain bug and security fixes without breaking the API, but still make progress on features and API changes in another release stream.

Python, for instance, is working in the same way. Python 3.9.x is still being supported while work is done on Python 3.11. Any serious bugs will be addressed in both streams.

I totally get why it's different for Home Assistant and why they are essentially just bumping numbers and don't care about backwards compatibility. But I think for libraries and modules it should be different, since they are being consumed by other applications. For applications using libraries it's easy to not care, but for the underlying libraries its important to maintain API stability.

[kbabioch]

We need to conclude this and agree on a (new) versioning scheme. One more call to @Guzz-T, @Bouni, @gerw @BenPru.

The current proposals are:

1.) Home Assistant versioning scheme, i.e. encoding the date and/or increasing some number without any specific meaning. 2.) Semantic versioning, i.e. something with major and minor versions, etc.

Personally I would prefer 2.), but it seems like back then there was a (small) majority towards 1.). Is this still the case?

[gerw]

I think that semantic versioning is more useful. With this, we can backport (and release) bugfixes to old stable versions.

[Guzz-T]

I think that semantic versioning is more useful. With this, we can backport (and release) bugfixes to old stable versions.

I totally agree with @gerw