sarif — archive

RE: comments on draft with no action

From: Laurence Golding
To: [email protected]
Date: Mon, 29 Apr 2019 16:27:00 -0000

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 <[email protected]> Sent: Monday, April 29, 2019 9:17 AM To: Larry Golding (Myriad Consulting Inc) <[email protected]>; James Kupsch <[email protected]>; [email protected] Subject: RE: comments on draft with no action In Appendix I, actionscript now appears twice and objectivec is gone k From: [email protected] [ mailto:[email protected] ] On Behalf Of Larry Golding (Myriad Consulting Inc) Sent: Thursday, April 25, 2019 12:02 PM To: James Kupsch < [email protected] >; [email protected] Subject: [sarif] RE: comments on draft with no action 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 From: Larry Golding (Myriad Consulting Inc) Sent: Thursday, April 25, 2019 11:50 AM To: James Kupsch < [email protected] >; [email protected] Subject: RE: comments on draft with no action Inline Thank you again, Jim, for the valuable feedback! Larry From: James Kupsch < [email protected] > Sent: Tuesday, April 16, 2019 12:49 PM To: Larry Golding (Myriad Consulting Inc) < [email protected] >; [email protected] Subject: Re: comments on draft with no action 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.