Process for handling major and minor changes

[erikbosch]

We need to agree on a process for how to handle major vs minor releases.

Background

Now and then we see a need to do backward incompatible changes, like changing name of a signal or changing semantic meaning. That should only happen in a major release, but we do not want to keep minor changes waiting until we plan for a major release. The solution would be to work with two branches, compared to today when we only use one.

But then we need to find a good practice for handling those branches.

[adobekan]

What if we focus more on deprecation. Until major release we keep both names, if we talk about changing the name of the signal/branch and then with major release we remove old name.

[erikbosch]

Deprecation works good for changes like:

• Renaming a signal (Copy the old and rename it, mark the old as deprecated)
• Removing a signal (Just mark it as deprecated)

Deprecation does not work (easily) for:

• Changing type, unit, description or semantics of a signal (while keeping the same name)

A typical example would be if we would like to change unit of Vehicle.Speed to m/s (instead of km/h). Another example is if we would like to do a refactoring like in #625 where signals keep their names, but there might be semantic changes. But maybe we should think of alternative solutions to having multiple branches, as that would require quite some work to keep branches in sync.

A thought that came to my mind is if we could support multiple versions of a signal in the same vspec. Taking the hypothetical unit change for Vehicle.Speed. If we would allow a syntax like below it would be possible for us to support multiple VSS-versions from the same file. I.e. let the tooling support a VSS version parameter and use it to select which definition to use.

Then of course, we would still need to decide what to release when we do a release. Taking the hypothetical example below, we maybe do not think the change in itself merits us releasing v5.0, so we could possibly before next AMM release v4.1 (using the old definition) and a v5.0a1 as a pre-release using the new definition (Alpha release, based on https://peps.python.org/pep-0440/). If a signal/branch has no vss-version attribute then it is assumed included in all versions currently supported. We most likely do not want to support more than 2-3 versions at a time. I.e. at some time we will consider v4.X as no longer maintained and then we can cleanup the *.vspec files accordingly

Speed:
  vss-version: 4
  datatype: float
  type: sensor
  unit: km/h
  description: Vehicle speed.

Speed:
  vss-version: 5+
  datatype: float
  type: sensor
  unit: m/s
  description: Vehicle speed.

[adobekan]

Changing datatype or unit, i would keep for the next version minor or major. While name change you can keep always two in parallel until you find it comfortable to deprecate from the system, basically it gives you a bit more freedom when it comes to implementation.

Also your proposal with tagging is quite similar to what we do with version release on git.
I go on git release, pick version 5.0 and Speed will be in m/s, if i go for 4.0 it would be in km/h. Am i missing something here?

[erikbosch]

Based on the discussion on the VSS meeting earlier this week I would say that changing unit from km/h to m/s is a semantic change, i.e. nothing that we can introduce in a minor release as it would cause a backward incompatible change.

The final result would be exactly as you say, if you download a VSS 4.X release it would be km/h, and for a VSS 5.X release m/s, but the question is how to handle it in the source *.vspec files. If it is OK that no VSS 4.1 is ever released we can just say that the next release will be VSS 5.0 release. That is more or less how we have done it in the past, when it is time for release we check if there are any backward incompatible changes or not. If not we do a minor release, if yes we do a major release. But if we need to work with VSS 4.X releases and VSS 5.0 release in parallel we need to have a way to separate changes in *.vspec files, either by different branches or by metadata.

[SebastianSchildt]

I would suggest the following:

• main moves forward to next major release (5) , i.e. we DO merge breaking if we deem them useful
• we do create a 4.next branch, for new PRs we need to check, whether a backport to the 4.x series is needed (i.e. if a non-breaking change is proposed, or a signal is added), and maintainers are responsible to ensure the relevant things are backported
• Next release can either be 4.x only or 4.x and 5.0

[erikbosch]

I agree on the comments from Sebastian above, but we should possibly discuss branch-naming. As of today we typically create a branch release/X.Y when we release something but we have not really described how to use those branches. For CI purposes it is maybe better to have a fixed name for the maintenance/minor-version, like maint, then it would be easy to setup CI so that it builds both master and maint.

[erikbosch]

Meeting discussion:

• Sebastian: Likely sufficient to support "current" and "next" release
• If someone wants to support an older version it is OK, but that is not the responsibility of the maintainers
• Terms not be clarified
• Conclusion: Agree that "multi branch/version" approach needed
• AP: Erik to write down process proposal for next meeting
• Sebastian: We need to agree that main/master is for next major, and that minor release is in some other branch
• Conclusion agreement on that master is for next major

[erikbosch]

A suggestion on how to handle major/minor created at https://github.com/COVESA/vehicle_signal_specification/wiki/VSS-Version-Governance-(Major-Minor)

Some things to discuss:

• Do we still want to use "deprecation" for the maintenance-branches. As I see it deprecation shall never be used on master branch, there we do the change immediately
• How long do we want to keep updating maintenance branches. Current proposal is "next major + 6 months" (or at least 12 months) which hopefully is feasible

[erikbosch]

Meeting notes:

• Sebastian: deprecation might still be useful. Time limits make sense, we shall write down when we do release