Intended content of a release

[erikbosch]

The latest release contain the following assets

• vss_rel_3.0.json
• vss_rel_3.0.tar.gz
• Source code (zip)
• Source code (tar.gz)

The first two are manually added. That tar.gz file contain output from all "supported" tools in vss-tools except binary, as binary output might be target specific). The json file (generated by vss-tools json exporter) exist in the tar.gz file as well but is also added separately to simplify showing VSS in online JSON tools.

@slawr has identified in a slack discussion that the content may be confusing and might need to be changed or better explained.

[slawr]

Input on Release Assets

I have a feeling I may have said this before, so apologies if I have and we discussed it..

Personally, I think the 'assets' of the release are presented a little strangely for people not very familiar with the project. Especially for newcomers to understand.

Looking at it from the perspective of a newbie who may have read the doc and is looking at a release to work with a specific version:

• The yaml is the single source of truth for the standard catalog but if I open v2.2.tar.gz I don't see the yaml, but generated serialisations with no doc or comment inside them to tell me that. Of course the newbie will not know this.
• The assets also includes vss_rel_2.2.json in the root and I might wonder is this .json the catalog, which is confusing as the doc talks about .yaml.. or maybe I'm just moving very fast and assume that the json is the source of truth. Side note: I see Daniel's explanation on slack that the json is there to drive the json viewer embedded in the doc.
• If I finally open the source code archive then I may then find a yaml file if I hunt around.

After a while you may figure out that the source code archive contains the catalog and that the v2.2.tar.gz contains generated output from vsc-tools, etc. but its not obvious early on.

How to improve that is a matter of details, but could be easily fixed in various straight forward ways. You could have a few lines in a readme.md/release.md released as an asset, which summarises what the files are using vX.Y.tag.gz filenames that don't need to be maintained. Another would be more descriptive archive names.

[erikbosch]

Meeting comments:

• Shall individual files be added separately? (i.e. not in *.tar.gz)

[slawr]

Deprecation

Should the review consider to what extent we document deprecation in the rule set or standard catalog?

Currently the release note has a "What's Changed" section that includes a summary line for all changes but finding changes is largely left to an end user exercise in vspec comparisons between releases.

[erikbosch]

So far for our releases we typically summarize the changes in a few lines and then also include an auto-generated release note ("What's Changed") with the headers of all commits. We do not have a detailed list showing exact changes in the vspec files.

But the question is - what changes does someone actually want to find or be informed of? It would be feasible to create and include (manually or automatically) a summary list of added/removed/deprecated signals, but do we also want to include changes of description, datatype and comment?

Concerning deprecation we have some guidelines in https://covesa.github.io/vehicle_signal_specification/rule_set/basics/#deprecation-since-version-21. So far it has worked quite well when removing/renaming a signal - if next planned release is a minor release we duplicate the signal and mark the old name as deprecated. If next planned release is a major release we just rename it. For other changes the deprecation keyword does not work, like if you change datatype, unit, description of instantiation, or add/remove properties. We cannot e.g. at the same time have one signal "Speed" with int16 as datatype and one with float as datatype.

[slawr]

My experience of commercial SDK development is that users appreciate upgrade guides that detail changes. That said we are not talking about binary releases and of course the standard catalog being plain text yaml lends itself to simple version comparisons by a user in their favorite tooling. If vspec compare handles that case, then thoughts turn to the cases that are not covered by it.

Changes to the rules might be one such case. That might only be clear in the documentation. Again source compare of the doc might show that, but as with vss-tools compare it may not be so obvious. This feels like an important one. Especially if the core tooling is not closely maintained to be in sync to it. Potentially an increasing problem as more use cases are served by new features like VSS Layers which in turn increases diversity/complexity. Basically, communicating rule changes loudly, clearly and repeatedly, rather than deep in PR details, will lead to better outcomes and therefore satisfaction.

'Big change' that you wish to clearly flag in that release or pre-warn for later release (as in deprecation) would be another. Thanks for the link to the depreciation rules. They make sense to me.

It doesn't lend itself to automation but personally I think I would aim at a light weight middle ground. Details can be largely handled by the change/PR lists and source compares by the user. I would have something in the release process for summarizing the bigger things like deprecation and rule changes. That need not be an upgrade guide, but its made clear that this is something you likely need to think about.