Versioning and Releasing

Versioning

Each version of gui-v2 is defined by a git tag, and consists of three parts: major, minor, and patch. For example: v1.2.3 has a major version of 1, a minor version of 2, and a patch version of 3. Every git tag should be associated with a "Bump version" commit sha1, and such commits should ONLY contain a single change (i.e., updating the version in the CMakeLists.txt to the next appropriate version number).

Major version

Major version changes only occur in very special circumstances; none are currently planned. The current major version of gui-v2 is 1.

Minor version

The minor version number relates to the version series of Venus OS which includes that minor version series of gui-v2. As such, the minor version of gui-v2 changes each time a Venus OS version update occurs.

For example: v1.0.x of gui-v2 was targeted at Venus OS v3.5x series, v1.1.x of gui-v2 was targeted at Venus OS v3.6x series, and v1.2.x of gui-v2 was targeted at Venus OS v3.7x series.

gui-v2's minor version numbers relate specifically and only to the version of Venus OS which will include gui-v2, and are not related to other factors (binary compatibility, library dependency versions, etc).

Patch version

The patch version number is incremented periodically (via a new tag), and this new "build" of gui-v2 will be made available for inclusion in a candidate (possibly beta candidate) release of Venus OS. Two consecutive patch versions of gui-v2 usually include a smallish amount of individual changes / commits (although the maximum allowable amount isn't defined in our process). We generally aim to tag a new version (and thus make a new build available for inclusion in a Venus OS release) approximately once per week, normally.

When a Venus OS series is close to leaving beta stage (i.e. close to becoming a final release candidate for public consumption) some things generally happen:

1. the number of individual commits per release should get smaller, possibly only one or two, to improve regression isolation
2. the frequency of tagging / new patch version may increase, as we fix and release important gui-v2 bugs on a daily basis as required
3. the frequency of tagging / new patch version may decrease, if we have fixed all gui-v2 specific bugs which block the release; because no new features or other risky changes should ever be merged close to a release (i.e. stabilisation period).

Branching

The main branch of the gui-v2 repository contains the content which is aimed for inclusion in the NEXT Venus OS series release. That is: while Venus OS v3.70 has not yet been released, main contains content aimed at Venus OS v3.70.

Once that specific version (e.g., v3.70) of Venus OS has been released, we create a new branch associated with that version (e.g. v3.70) which contains everything in main at that point. New commits added to the main branch from that point forward will NOT be included in future Venus OS releases of the same series (e.g. v3.7x); instead, that new content in main will only be included in the next Venus OS series release (e.g. v3.80) in future.

Changes which are wanted also for updated releases of the the older Venus OS series (e.g. v3.7x) should be cherry-picked from main into the series-specific branch (e.g. v3.70) using git cherry-pick -x SHA1, and then subsequently the patch version in that branch should be bumped, and a new patch version tag should be created, to create a build for inclusion in the next update release of that (older) series of Venus OS. That tag version specifies a "backport release" (as it is a version for a "previous" version of Venus OS other than the one which is targeted by main branch).

Releasing

Every new tag specifies a "release" of gui-v2, which may or may not be included in a "release" of Venus OS.

When a new release is made, an entry associated with that release should be added to https://github.com/victronenergy/venus-private/wiki/todo and the format of the entry should conform with the format described in https://github.com/victronenergy/venus-private/wiki/todo-way-of-working.

It should contain a changelog which is generated using the one-liner script described in the Change Log Generation section below.

For example, let's say we just tagged version vX.Y.Z in main branch, where there exist three commits/changes since the previous tag: "Fix bug in component C", "Add foo feature to bar", and "Fix critical bug in component D", where the first commit makes use of a path which was only added in venus-platform vA.B.C, and the second commit requires adding a new integer setting with default value 1 with path "Gui2/SomeNewSetting" to the system, we might have the following entry:

* gui-v2 and gui-v2-webassembly vX.Y.Z
  * Dependencies
    * venus-platform vA.B.C
    * Requires a new setting: Gui2/SomeNewSetting 1 i 0 1
  * Changelog
    * Fix bug in component C
    * Add foo feature to bar
    * Fix critical bug in component D

The Venus OS maintainer may then pull that updated gui-v2 version into a build for the next release of the current version of Venus OS.

Backport releasing

If a given release of gui-v2 is a "backport release" (i.e. created from a series specific branch like v3.60 instead of main, and aimed at a previous series of Venus OS e.g. v3.60), then you need to add a specific flag to the entry associated with the gui-v2 release.

For example:

* gui-v2 and gui-v2-webassembly vT.U.V (**backport candidate** for v3.6x series)
  * Changelog
    * Fix critical bug in Component D

However, usually a release will be main from the main branch at the same time as the backport branch, and in this case you should instead mark individual backported commits separately in the main branch release's changelog. For example:

* gui-v2 and gui-v2-webassembly vX.Y.Z
  * Dependencies
    * venus-platform vA.B.C
    * Requires a new setting: Gui2/SomeNewSetting 1 i 0 1
  * Changelog
    * Fix bug in component C
    * Add foo feature to bar
    * Fix critical bug in component D (**backport candidate** already released in gui-v2 vT.U.V for Venus OS v3.6x)

If you have NOT YET cherry-picked a commit from main to the backport branch (as you have not been given permission to backport it), but you think that it SHOULD be backported, you may mark it for discussion in the following way when making a main branch release:

* gui-v2 and gui-v2-webassembly vX.Y.Z
  * Dependencies
    * venus-platform vA.B.C
    * Requires a new setting: Gui2/SomeNewSetting 1 i 0 1
  * Changelog
    * Fix bug in component C
    * Add foo feature to bar
    * Fix critical bug in component D (**backport candidate** not yet backported)

... or alternatively just ping someone on slack to ask about it. This is ESPECIALLY important if the fix entails any dependency updates!!!

Examples

Imagine that the main branch is currently targeted at Venus OS v3.70 and so the most recent tag in main is v1.2.x. Developer A creates a new code change which fixes a bug. Their commit message links to the issue number properly. They create a PR which is targeted to main branch. PR is reviewed, tested, and approved for merge. Developer A should rebase-merge their change into main branch via the github UI.

At this point, the developer notices that there have been a significant number of changes in main since the last tag, and decide to create a new gui-v2 release. So, they then do the following:

1. build and test current main content on all platforms, ensuring no regressions have been introduced.
2. create a "Bump version to v1.2.y" commit in main branch (where y is one larger than the most recent patch version number tagged in the main branch of gui-v2).
3. push it to the git repository remote with: git push origin main:main
4. create the new tag locally with: git tag v1.2.y
5. push the tag to the git repository remote with: git push origin v1.2.y
6. ensure that the github action for the tag (NOT the commit) succeeds
7. generate a changelog and add an entry to the release-todo wiki as described above

At that point, the developer is told by the Venus OS maintainer that a specific change is wanted for the backport release (i.e. v3.6x series of Venus OS). So, they checkout the v3.60 branch, cherry-pick the change with git cherry-pick -x SHA1, and then perform the following steps:

1. build and test current v3.60 content on all platforms, ensuring no regressions have been introduced.
2. create a "Bump version to v1.1.z" commit in v3.60 branch (note the minor version of 1 is for Venus OS v3.60 series releases, and here z should just be one larger than the most recent patch version number tagged in the v3.60 branch of gui-v2).
3. push it to the git repository remote with: git push origin v3.60:v3.60
4. create the new tag locally with: git tag v1.1.z
5. push the tag to the git repository remote with: git push origin v1.1.z
6. ensure that the github action for the tag (NOT the commit) succeeds
7. add a "backport release" entry to the release-todo wiki as described above

Finally, imagine that the version of Venus OS which is currently including the main branch content gets released. For example, imagine it is v3.70. Now, the developer must create a new "backport branch" for this release (i.e. called v3.70), and switch main branch's minor version to properly describe that it is now aimed at the NEXT release series of Venus OS.

They must do the following:

1. Checkout the main branch locally, and ensure it contains the most recent remote content, i.e.: git fetch origin && git checkout main && git reset --hard origin/main
2. Reset their local copy of main branch back to the most recent tag (which should have been released in Venus OS v3.70), i.e.: git reset --hard v1.2.x
3. Create a series-specific branch from main at this point, named for the series e.g. v3.70, i.e.: git push origin main:v3.70
4. Reset their local copy of main branch up to the latest remote main content again: git reset --hard origin/main
5. Bump the minor version in main now that it will be targeted at the NEXT release series of Venus OS (i.e. v3.80), to v1.3.0. Push this bump-version commit to the remote main, then tag the new version git tag v1.3.0 and push that tag also. Add an entry to the release-todo wiki for this new v1.3.0 version.

If you have any doubts: don't do anything, just ask Chris for help.

Commit Messages

To simplify the task of changelog generation when making a release, it is important that every commit message follows a specific form.

The commit title should be prefixed with a keyword which identifies the type of device or feature being modified, followed by a colon, and then a concise summary of the change. The entire commit title must not exceed 72 characters in length.

The commit description should detail why the change the was made (unless it is obvious), and it should explain the reasoning behind any design decisions (unless the change is too simple to warrant such explanation). It should also list any dependencies or system-level assumptions that the change relies on. It must end with a backlink to the issue that the commit is associated with. Each line of the description must not exceed 72 characters in length.

In summary, the format of the commit message is as follows:

<Keyword>: <What was done in the commit>

<Why the change was made>
<Design decisions>
<Dependencies>

[Fixes/Contributes to issue] #ABCD

For example:

Multi RS: Fix calculation of total AC input power

Previously, the code summed power from a single phase 3 times,
instead of summing the power from each of the 3 different phases.
This commit ensures that we iterate over the phases correctly
during summation.

Use a 1Hz timer to trigger power re-calculation to align with
gui-v1 and to ensure that we don't re-calculate too frequently.

Fixes #1261

Commit Keywords

When reading the changelog, users want to know if a particular change will affect their system. Each user will have different devices connected to their system, and they know which device types they have. As such, the keywords we use as commit title prefixes should map to specific device types (or categories of devices).

When choosing a keyword, the developer should select the most-specific keyword which encapsulates the scope of changes made in the commit.

For example:

1. if the developer is making a change which specifically affects settings of Multi RS inverter-charger units, they should choose the "Multi RS" keyword
2. if the developer is making a change which affects settings of all types of inverter-charger units, they should choose the "Inverter/Charger" keyword
3. if the developer is making a change which affects settings pages generically, they should choose the "Settings" keyword
4. if the developer is making a change which affects performance only (not functionality) of some subset of pages, they should choose the "Performance" keyword

The keywords fall into the following rough categories, listed here from least-specific to most-specific:

• A) keywords for changes whose scope is not limited to any specific device type or application page
• B) keywords for changes whose scope is limited to a specific application page
• C) keywords for changes whose scope is limited to a specific aggregation service
• D) keywords for changes whose scope is limited to a specific class of device types
• E) keywords for changes whose scope is limited to a specific device type

Note that the keywords for (D) above roughly map to the DBus API paths (see https://github.com/victronenergy/venus/wiki/dbus), however in some cases they will differ slightly (for more specificity or clarity).

The list of keywords follows, from least-specific to most-specific:

# A: broad scope keywords
Performance
Translations
UI Controls

# B: page keywords
Settings
Notifications
Levels
Overview
Brief
Boat
Controls             # i.e. control cards view page
Switches             # i.e. switches cards view page

# C: aggregation service or subsystem keywords
AC System
DC System
AC Load
DC Load
Platform             # i.e. venus-platform related fix
CAN Bus              # i.e. RV-C etc
MQTT
Inverter/Charger     # for changes applying to any type of inverter/charger services
AC In                # generic AC input issues

# D: class of device type keywords
PV Inverter
Inverter             # i.e. VE.Direct inverters plus Inverter RS
Vebus                # i.e. VE.Bus services
AC Charger
Solar Charger
EVCS
DCDC Converter
Battery
ESS
Genset
Alternator
Fuel Cell
Meter                # i.e. grid or genset meter
Heatpump
Motordrive
Relays
Tank
Temperature
Switch               # i.e. a switching device, NOT the Switches pane view/page
GPS                  # i.e. global positioning system
BLE                  # i.e. bluetooth low energy

# E: specific device type keywords
Multi RS
Lynx BMS
... etc

Changelog Generation

If all commits use the formatting and keywords specified above, generating a changelog for a release can be done with:

git log --pretty=format:%s | head -n$(git rev-list $(git describe --abbrev=0 --tags $(git rev-list --tags --skip=1 --max-count=1))..HEAD --count) | sort

if you have already tagged the release.

If you have not yet tagged, you can use:

git log --pretty=format:%s | head -n$(git rev-list $(git describe --tags --abbrev=0)..HEAD --count) | sort