Versioning and Releasing - victronenergy/gui-v2 GitHub Wiki

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) two things generally happen:

  1. the number of individual commits per release should get smaller, possibly only one or two
  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.

For example, let's say we just tagged version vX.Y.Z in main branch, where there exist two commits/changes since the previous tag: "Fix bug in component C" and "Add foo feature to bar", 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

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 vX.Y.Z (**backport candidate** for v3.6x series)
  * Changelog
    * Fix critical bug in Component C

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 with: git tag -a v1.2.y -m "Short description of most important changes since last tag"
  5. push the tag to the git repository remote with: git push origin v1.2.y
  6. 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 with: git tag -a v1.1.z -m "Short description of cherry-picked change"
  5. push the tag to the git repository remote with: git push origin v1.1.z
  6. 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 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.