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

["Larry Golding \(Comcast\)" <larrygolding@comcast.net>]

I’ll answer the parts of your question in order:

 

Are the values provided by SemVer critical to SARIF?

 

No, but they are valuable, as I’ll explain below. I’m willing to drop from SHOULD to MAY. I’d object to omitting it from the standard.

 

How will a consumer make use of it?

 

Let’s consider why the standard includes any version properties in the tool object. It’s to allow consumers (humans or automated systems) to reason about the capabilities of the tool that produced the log file. Did this version have the fix for the bug that prevented the tool from reporting certain results? Did it have the enhancement that provided more detailed code flows? Was it a pre-release version?

 

Tool versioning information is a proxy for questions like this. A consumer uses the tool version to answer those questions.

 

So it makes sense to at least permit SARIF producers to include a version number in a format that provides the most precise semantics.

 

Have I missed other key values?

 

Depends what you mean by “key”. SemVer certainly provides other values from the two that you mentioned (chronological sorting and breaking changes):

 

• Identification of unstable versions (major version 0)
• Distinction between bug-fix-only releases (1.2.0 => 1.2.1) and back-compatible feature enhancements (1.2.0 => 1.3.0)
• Identification of pre-release versions (1.2.0-beta.1)
• Ability to include build information (1.2.0+build.20180503.093902.x86.release)

 

Larry

 

From: Michael Fanning <Michael.Fanning@microsoft.com>
Sent: Thursday, May 3, 2018 7:17 AM
To: Larry Golding (Comcast) <larrygolding@comcast.net>; sarif@lists.oasis-open.org
Subject: RE: [sarif] Clarify and relax requirements on tool.semanticVersion

 

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