Zigbee2mqtt: Versionning... with GitVersion?

[carldebilly]

SemVer ?

May I suggest having something to set versionning of dev branch?

1.6.0.,.. really?

Because currently the dev version is tagged as 1.6.0 in the MQTT topic... and I'm running the latest dev version.

{
    "version": "1.6.0",
    "commit": "36c7a27e6c632e0450db18279fc46a1d01365579",
    "coordinator": {
        "type": "zStack30x",
        "meta": {
            "transportrev": 2,
            "product": 2,
            "majorrel": 2,
            "minorrel": 7,
            "maintrel": 2,
            "revision": 20190425
        }
    },
    "log_level": "debug",
    "permit_join": false
}

I want to start supporting the new force_remove feature that has been introduced this morning, but there's no way for Z2MA to _know_ if the feature is available.

Following SemVer 2.0, the version should be something like 1.7.0-dev

Suggestion: GitVersion

In Zigbee2MqttAssistant, I'm using GitVersion to fix this problem: each time a build is done, a new version number is generated automatically.

[Koenkk]

Good idea, could you make a pr?

[carldebilly]

Let me try something...

[Koenkk]

Thanks, would be great, a skeleton/guidance is already OK (I don't have any experience with it for now).

[carldebilly]

Let's talk about alternatives...

Goal

The goal is to make sure we have a different version number each time a change is made. The version should be incremental, so we're able to say something like _"the feature X is available in version Y+"_.

Option 1: _Mainline branch_ development with publishing channels

In this approach, a build is done each time a new commit is made in the "master" branch.
Complex changes could required a _feature branch_ and are merged into the master branch once they are stable enough.
Each merge or direct commit to mainline branch are generating a build with its own version number. The build is published in a pre-release channel (usually called "dev" or "beta"). Once the build is certified as "stable", the same build version got published into stable channel.
That means there's no new build once a version got promoted to stable branch, the package just go published to a different publishing channel.

That's the approach I'm using in _Zigbee2MqttAssistant_, because it's less management and very straightforward: once I know a version is stable, I just publish it to the stable channel.

Pros

• Easier to manage
• Once a packge/build is certified,

• Version numbers are always incremental over time

  Cons

• No version number / packaged published for _feature branch_

• When you have a package, you have no way to know from which channel it's from... the version itself is not enough because all package version are tagged as _release_ per SemVer semantic.

How it works

• Similar to what you're currently doing: incremental commits into a single branch.
• Each commit & merge will be published with their version number on docker as a tag + the "dev" tag
• A "multi-stages" process in AzureDevops can be triggered manually when you want to promote a build to stable, which would add the tag "latest" to published docker image.

Option 2: Branch development with each branch having a specific CI/CD

This approach is more complex, but a lot more flexible: each channel (_dev_, _stable_ or event a feature branch) got its own build and publishing channel. The versionning can use SemVer to tag the package according to its source branch.

I think this approach is more appropriate for Z2M and gives flexibility for feature development.

Pros

• You know where a package is from according to its version number
• Easy to create "feature" and publish packages for this feature without affecting those using the stable or even the dev version.

• Easy to "patch" stable version without waiting for features in development to be stabilized.

  Cons

• More complex to manage, requires to master merging branches, specially when publishing a stable version

• May need a staging channel to certify stable versions before publishing them for everybody because they are the result of a merge which could potentially introduce bugs.

[Koenkk]

What about setting just "version": "dev" for the dev branch? (https://github.com/Koenkk/zigbee2mqtt/blob/master/package.json#L3).

In this way you can determine if someone is on the dev branch, the user itself it then responsible for keeping up-to-date (so from a zigbee2mqtt assistant perspective you can assume that somebody is always on the latest, if not, it's the users problem).

I don't want to end up in micro-managing the versioning here..

[sjorge]

Speaking of versioning... for the next release... can we perhaps keep 'master' as the development place and tag the 1.x.0 in a branch called 'stable' ?

[Koenkk]

@sjorge no, as on the bare metal installation you will have
a git repository checked out (https://www.zigbee2mqtt.io/getting_started/running_zigbee2mqtt.html), so this will break many existing installations. Zigbee2mqtt follows the git flow principles (https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)

[Koenkk]

The dev branch will now have the version number + dev (e.g. 1.7.0+dev), in this way you should be able to distinguish between a release version and the dev branch. Assuming this can be closed now.