VSS Version Governance (Major Minor)

This page intends to give guidelines on version governance

General Approach

• We intend to have at least two releases per year, but unless there is a good reason not more than 1 major release per year.
• The "master" branch is the default branch and contains the content for the next major release.
• In addition to the "master" branch we may have one or more branches like "4.X" or "3.X" with content that potentially could be included in a minor release.
• Pull Requests (PRs) shall by default be targeting the "master" branch
• If a PR is considered "minor", then project maintainers shall after the PR has been merged to "master" do a cherry-pick or merge towards relevant minor-branches (like "4.X")
• At least twice a year the VSS project shall make a decision on what to release (if anything)
  • A minor release shall typically be created if there is "anything" in the corresponding branch. It is no problem to release minor releases more than twice a year if needed/requested
  • A major release shall be created if there are significant changes in master branch, but there should be good reasons to release major releases more frequently than once a year (like high inflow of features)

Classification of major/minor changes

In general a major change is something that breaks backward compatibility, changes semantics or introduce a major set of new functionality.

List of changes that NOT shall be included in minor releases:

• Changing unit of a signal
• Changing name of a signal
  • But could in many cases be included in the minor release by using the "deprecated" approach, i.e. adding a signal with the new name and mark the old name as deprecated
  • TBD: Do we still want to use deprecation as concept? Or is it better to just change name in "master" and keep minor-branches unchanged?
• Changing datatype of a signal, even for "simple ones" like uint8 to uint16
  • Rationale is that we do NOT know if downstream implementations can handle (simple) type mismatches, we have no recommendations that implementations shall be flexible on types, like accepting a response/request of type A if the value could be cast to type B.
• Changing or adding "allowed" literals
• Using new features that require that a new VSS-tools major version is used
• Changing description/comment resulting in semantic change of signal
  • Example: If we change description of Vehicle.Speed to state "Vehicle speed measured at wheels" rather than just "Vehicle speed" then that could be considered as a semantic change
• For vss-tools: *: Any changes resulting in changed output or require additional arguments. Exception is obvious error corrections.

List of changes that can be included in a minor release:

• Adding a signal
  • A possible exception could be if the number of signals are significant
• Adding/Improving/Changing description and comment, if it does not change semantic meaning of signal
• Changes when current description contain obvious errors
  • Example: Changing type from int8 to uint8 may be OK if description or range says that negative values may be used
• Upgrading vss-tools minor version.
• For vss-tools: *: Adding a new tool or new arguments that does not affect (default/existing) behavior of existing tools.

General Branch Strategy

• "master" branch is the default branch and will be used for the next major release
• Whenever a major release is created a maintenance branch for minor releases shall be created
  • example: When v5.0 is released a branch 5.X shall be created, to be used for minor releases in the 5.X series
• A patch branch, like "5.0.X" may be created as well, but only if needed
• The project ambition for maintenance branches is to maintain them:
  • For 1 year after the major release
  • But at least 6 months after next major release. This gives downstream projects a 6 months window to migrate to the newer version
  • TBD: Do we consider the time limits above reasonable?
  • Example: VSS 4.0 was released 2023-05-22. If we assume VSS 5.0 will be released 2024-05-01 then minor changes on master will be merged/cherry-picked to the 4.X branch until 2024-11-01.
  • A minor release shall be created before a branch is "closed"
  • If requested contributors may volunteer to maintain a maintenance-branch for a longer time