Good catch! Fixed in the change draft for #402 that Iâm about to push.
I see that the current draft has an entry for âobjectiveâ. Thereâs no such language, right? It looks like I just chopped off the âcâ from âobjectivec", right?
Thanks,
Larry
From: Yekaterina O'Neil <katrina@microfocus.com>
Sent: Monday, April 29, 2019 9:17 AM
To: Larry Golding (Myriad Consulting Inc) <v-lgold@microsoft.com>; James Kupsch <kupsch@cs.wisc.edu>; sarif@lists.oasis-open.org
Subject: RE: comments on draft with no action
In Appendix I, âactionscriptâ now appears twice and âobjectivecâ is gone
k
The change draft is:
https://github.com/oasis-tcs/sarif-spec/blob/master/Documents/ChangeDrafts/Accepted/sarif-v2.0-issue-376-kupsch-additional-feedback-2.docx
Larry
Inline
Thank you again, Jim, for the valuable feedback!
Larry
Larry,
Sorry I didn't see the comments earlier. I didn't scroll far enough before looking at the change draft and the github issue and didn't see that there was comments on the items not updated in the document.
My comments on some of the items are below in red.
Jim
On 4/15/19 4:31 PM, Larry Golding (Myriad Consulting Inc) wrote:
Hi Jim,
With the exception of "location relationships" which we're still considering, the items you list below are the ones we decided not to take. I sent you an email with responses on all your items, including rationales for the ones we did not take. I've attached it here to share it with everybody. I suppose I should fill out #366 with the rest of the responses.
Thanks,
Larry
The following suggestion was rendered moot by the changes we accepted:
-
Appendix D no longer uses the lack of a converter version number to justify the now-removed advice against synthesizing properties, so the text that incorrectly stated that a converter doesnât have a version number has been removed.
We could discuss whether the general guidance for version numbers on tool components should be changed. As the spec stands, all the versioning properties
MAY be present. Iâd be open to tightening that, for instance, âAt least one of version or semanticVersion
SHOULD be present.â
This would be reasonable statement to add about the versions.
[Larry] Done:
3.19.2 Constraints
At least one of
version (Â3.19.10) and
semanticVersion (Â3.19.9)
SHOULD be present.
Here are explanations on some of your other feedback items:
-
With regard to your question about the distinction between
toolComponent.productSuite, product, and
name, think âMicrosoft Office/Excel/Excel Charting Toolâ.
It would be useful to state that name is intended to be displayed to users as the tool's name
[Larry] Given the name of the property ("name") and the fact that itâs a localizable string, I think that is sufficiently clear as the spec stands.
and that viewers may display this as part of a table the name should be short; ideally it should not include line breaking characters, the company name, version information, product or productSuite that are available
in other properties.
[Larry] Given the existence of the corresponding property "fullName", the contrast in the examples between them, and the new section on âproduct hierarchy propertiesâ (see below), I donât think this is necessary.
Move the product and productSuite section to immediately follow the name section as they are similar concepts.
[Larry] Done
In the product and productSuite properties state that these can be used to form a hierarchy of related software: name can be part of a product which can be part of a productSuite.
[Larry] Done:
3.19.7 Product hierarchy properties
The
name (Â3.19.8) or
fullName (Â3.19.9),
product (Â3.19.10), and
productSuite (Â3.19.11) properties establish a hierarchy of related software: the tool component
identified by name and/or
fullName is part of the product named by
product, which in turn is part of the product suite identified by
productSuite.
-
With regard to your suggestion to provide a short (20-30 character) human readable name for a
reportingDescriptor that is localizable and not necessarily stable, we do have such a property:
reportingDescriptor.name. See Â3.46.7 in the provisional draft (Â3.44.7 in the e-ballot-3 draft). We donât provide explicit guidance on its length, but the example given ("SpecifyMarshalingForPInvokeStringArguments")
conveys the idea.
There should be advice similar to the above section. Viewer should use the name of the descriptor (or the id in its absence) to label this type of issue to users. The name should be short as it may be displayed
in tabular views that have limited horizontal space. It should not include line breaking characters.
[Larry] I think the example is sufficiently clear, and given the spec says that this is âa localizable string (Â3.5.1) containing an identifier that is understandable to an end userâ
I donât think I need to tell a viewer that it can display it as an issue label. -
With regard to your suggestion in Â3.15.2 (externalPropertyFileReference.location) that we not restrict
uriBaseId, this section does not actually introduce a new restriction. Â3.4.4 (artifactLocation.uriBaseId property) already says:
If the uri property contains an absolute URI, the
uriBaseId property SHALL be absent.
Although strictly speaking thereâs no need to repeat that in Â3.15.2, I think itâs helpful, so I added
these words:
If location is present, its
uri property SHALL be an absolute URI using the
sarif scheme (Â3.10.3), and
so (by Â3.4.4) its uriBaseId property
SHALL be absent.
My point here was that this text says that if you are using a sarif scheme URI, then the location SHALL NOT include a uriBaseId. I think that the uriBaseId should be allowed. It seems perfectly reasonable to create
a baseUriId named INLINED that has a uri="sarif:/inlineExternalProperties", and to then have a location of {uriBaseId="INLINED", uri="0"}. To support this, the text should just say that the resolved location SHALL be an absolute URI with a sarif scheme.
[Larry] Agreed: âIf
location is present, its
uri property
SHALL resolve to an absolute URI using the
sarif scheme (Â3.10.3).â
For the following suggestion,
we have two proposals:
-
âAdd more languagesâ. We donât want to be in the business of proposing an exhaustive list, or even of presenting a list that spans many pages. Here are two options:
a) In the Appendix, add a statement to the effect that this list is just a start, and we expect the community to develop it over time.
b) Remove the Appendix.
I would add just a couple of more languages to cover more of the languages in the top-n lists (if you add these and format as 2-columns it will fit on one page).
visualbasic
visualbasicdotnet
objectpascal
r
d
groovy
lisp
lua
prolog
scheme
ada
rust
julia
haskell
erlang
actionscript
clojure
ocaml
[Larry] Done
We decided not to take the following suggestions:
-
With regard to the suggestion to introduce toolComponent.abbreviatedName, we prefer to add guidance to the effect that the tool name should be narrow because you never know where itâs going to be displayed, and if the
name is long, at least make sure that its leading portion is sufficiently informative to survive the name being truncated.
Adding guidance would be useful for the tool name and descriptor names would be useful. There is commentary in 11 and 12 above.
[Larry] Not done. -
With regard to the guidance around toolComponent.shortDescription and
fullDescription: We understand that converters canât always follow the guidance; converters are always at the mercy of the native output format. And a tool author who writes in a language with no sentences, or who writes
a message whose first sentence canât be readily identified, should follow the guidance and supply both short and full descriptions.
Unless a first sentence algorithm can be defined, then viewers can not follow this document. It would be better to just say that if the shortDescription is not present, viewers MAY displays a truncated version of
the fullDescription such as the first 100 characters, the first paragraph, or the first sentence. This description is something that a viewer can easily do and gives the viewer latitude in how to truncate the text.
[Larry] Done:
The
beginning of fullDescription (for example, its first sentence)
SHOULD provide a concise description of the tool component, suitable for display in cases where available space is limited. Tools that construct
fullDescription in this way do not need to provide a value for
shortDescription (Â3.19.17). Tools that do not construct
fullDescription in this way
SHOULD provide a value for shortDescription.
NOTE: The rationale for this guidance is that in the absence of
shortDescription, a viewer with limited display space might display a truncated version of
fullDescription, for example, the first sentence (if a sentence is identifiable), the first paragraph, or the first 100 characters. If this guidance is not followed, that truncated description might not be understandable.
-
Likewise for toolComponent.shortDescription and
fullDescription.
[Larry] I assume you meant reportingDescriptor on this one (or maybe I made a mistake transcribing your feedback). In any case, Done on reportingDescriptor as well. -
Likewise for the guidance in Â3.11.3 about plain text messages (we did take the suggestion to remove the restriction to a single paragraph).
[Larry] I removed the requirement for complete sentences since so many plain text messages occur in context where only a fragment or a few words is needed. Interestingly, we never had corresponding guidance on Markdown
messages.