VSS Version Governance (Major Minor)

This page intends to give guidelines on version governance

Version Lifetime based on the principles below

Version	First Release	Status	EoL	Comment
v3.X	2022-08-09	EoL	2023-11-02 (six months after VSS v4.0)
v4.X	2023-05-02	Supported	Six months after v5.0, or at earliest 2024-05-02 (1 year after v4.0)

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)

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.

"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 release-branch (like release/5.0 or release/5.1) may be created already at feature freeze but shall be created at latest at release
- The release branch shall never be deleted (see discussion in Issue 704)
- After release the branch may only be used for low risk changes intended for patches. Larger changes shall be added to the maintenance branch (like 5.Xinstead)
A patch branch, like "5.0.X" may be created as well, but only if needed. No defined end-time for patches/fixes.
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
- 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