search

home-assistant / organization

:briefcase: A repository for discussing the organizational matters of Home Assistant
Other
4 stars 1 forks source link

Semantic Versioning #6

Closed frenck closed 6 years ago

frenck commented 6 years ago

I'd like to bring up versioning of parts @ the Home Assistant org.

Problem

It seems like currently, we are doing incremental by simply upping a number, but as soon as we release a patch fix, we'll add some extra info to the existing version (e.g. 0.60 becomes 0.60.1). The problem with this approach is that the length / semantic of the version number is not consistent.

There are even places where we use a date as a version number, which I personally consider bad practice (but I'll guess it does the trick).

Suggestion

I would like to suggest to use sematic versioning. It is well documented, and there are even tons of libraries available, in almost every language, that can handle those.

Could solve things like:

Personally, I use this on my add-ons (No, I do not think this applies to Home Assistant (well maybe to the Supervisor of Hass.io):

Releases are based on [Semantic Versioning][semver], and use the format of MAJOR.MINOR.PATCH. In a nutshell, the version will be incremented based on the following:

What do you think?

https://semver.org/

balloob commented 6 years ago

Every version of Home Assistant contains a breaking change, hence the higher version.

For the frontend, well it's really just a snapshot. Nothing is automated on that side so I just add a timestamp on it and push it to PyPi.

Which other artifacts do we have? Oh I guess the Hass.io add-ons. We should bump them all to 1.0.

maddox commented 6 years ago

The problem with using Semantic Versioning for something like an app or a package as big as Home Assistant, is that its concepts rarely map. Semantic Versioning was developed for libraries that other apps and libs depend on. Its rules are set in a way that other developers can infer what kind of changes to expect with the version number update. Its rules exist to help package managers make better decisions on how to upgrade dependencies.

Applications just don't have this sort of issue. There is nothing that depends on version 0.54.2 of Home Assistant.

There are even places where we use a date as a version number, which I personally consider bad practice (but I'll guess it does the trick).

In my opinion, a date is literally all you ever need for a version number. For applications that you rarely care about going back a version, who even cares? Version numbers for applications are a relic of the past and are meant more for developer teams, support, and marketing. Ohh! 2 point oh is out!!

In the days of automatic backgrounded updates and open source applications, what does 0.60.1 even mean anymore? How's it different than 60.1. All that most people care about, is that they're on the newest version.

In the case of Home Assistant, which has a bi-weekly release schedule, it almost make more sense to use a date, heh.

I think the most important thing for Home Assistant is that the release notes stay as thorough as they have been. The Breaking Changes section is crucial and to me is the most important part. I have a place to go read about the new release and prepare my configuration for an upgrade. I could care less what the version number is.

frenck commented 6 years ago

The main use case of my question is really to keep the version numbering consistent. Right now its format varies, I would love to see this would be kept consistent. e.g., 0.61 vs 0.61.0. This would keep the format consistent, even when a patch version was released (which happened a lot lately).

Secondly, it allows developers to check for specific versions using libraries that support "semantic" versioning (even though Home Assistant is not actually using it...).

My personal use-case: Add-on requires at least Home Assitant 0.61... I can't use semantic versioning libraries or tools to check against it... since 0.61 is not valid. 0.61.0 would be valid though.

Add-on wise I could solve this using the GNU sort (version sorting) nevertheless, this is not part of Alpine by default and installing it would require coreutils adding about 10Mb to each image for that a little utility that actually can't do "advanced" version checking (conditions).

../Frenck

balloob commented 6 years ago

Where do you get the version from? Inside the Home Assistant Python code we always add a 0. Is this for the Docker image tags?

frenck commented 6 years ago

@balloob Hass.io API

brammittendorff commented 6 years ago

When you take a look at big...

Python frameworks: https://github.com/django/django/releases https://github.com/Pylons/pyramid/releases

C++: https://github.com/tensorflow/tensorflow/releases https://github.com/pytorch/pytorch/releases

And so on with every major framework, application or other coded stuff. They make use of https://semver.org/ because this is the most used and reliable standard to hold on to.

Even npm made documentation for it: https://docs.npmjs.com/getting-started/semantic-versioning

Also python itself uses semver: https://www.python.org/downloads/source/ https://github.com/python/cpython/releases

Gitflow recommends it: https://gitversion.readthedocs.io/en/latest/git-branching-strategies/gitflow/

The point that this application or software is to small is IMHO not true. A project should be structured as well as you can do from the beginning, not only when it is bigger. That said, the hassio project is so big you have addons that depend on your project and code, so they will need good versioning.

For what it's worth; I suggest to still try to use the https://semver.org/ way, even if this Issue is closed.

mjrider commented 6 years ago

adding my 2 cents:

  1. home-assistant is getting a fast growing install base, tackling this issue sooner is better then later
  2. home-assistant is a library/api from the addon perspective, and that is one of the major 'users'

Adding the ability for addons de define minimum/maximum versions which are compatible gives a more stable end-user(human) experience if home-assistant is actual checking for this in addons on installation/upgrade. Exposing this and sticking to the rules of semver gives addons them the ability to work around incompatibility issues in the api or bugs in older versions, or forcing addon updates before working again, preventing issues when the addon depends on behaviour which isn't available anymore