RE: [sarif] Clarify and relax requirements on tool.semanticVersion

[Michael Fanning <Michael.Fanning@microsoft.com>]

When I think of SemVer, I see two clear values. 1) the version information is sortable, providing a (presumably) chronological ordering of tool versions, 2) it provides semantics for breaking changes in tools.

 

Can you articulate why you believe these values are critical to put in a SARIF file? How will a consumer make use of it? Have I missed other key values in your estimation?

 

At this point, I don’t have clear line of sight into why this is a SHOULD (and not a MAY or emitted from the standard altogether). Can you help make the case again?

 

 

From: sarif@lists.oasis-open.org <sarif@lists.oasis-open.org> On Behalf Of Larry Golding (Comcast)
Sent: Wednesday, May 2, 2018 3:35 PM
To: sarif@lists.oasis-open.org
Subject: [sarif] Clarify and relax requirements on tool.semanticVersion
Importance: High

 

The spec currently says the following about tool.semanticVersion:

3.12.4     semanticVersion property

In a log file produced by an analysis tool, a tool object SHALL contain a property named semanticVersion whose value is a string containing the tool version in the format specified by [SEMVER].

 

There are two problems.

 

1. The wording “a string in the format specified by [SEMVER]” is too loose. It made people think that any three-component version number like “3.2.1” qualifies as a SemVer, whereas in fact SemVer carefully defines the semantics of each of those three components. The intent of SemVer is that you can look at any two version numbers and tell whether there are breaking changes between them.
   
   I would change this to clarify that if you populate semanticVersion, then you must conform in syntax and semantics to SemVer.

 

2. When I wrote the words “a tool object SHALL contain a property named semanticVersion”, I really did mean to say to tool vendors: “You want to use SARIF? Then get on board with SemVer!”. But I regret that now. You just can’t ask tool vendors to change their versioning strategy just to use a wonderful new output format. I’d like to change that to SHOULD.

I propose the following, to address both issues:

 

In a log file produced by an analysis tool, a tool object SHOULD contain a property named semanticVersion whose value is a string that SHALL conform to the syntax and semantics of [SEMVER].

 

I took some pains over the wording. I want to convey that you don’t have to supply it, but if you do, it needs to be a real SemVer.

 

Thoughts? If we agree, I’ll file a CSD.1 issue and fix it.

Larry