sarif — archive

Re: [sarif] RE: comments on draft with no action

From: Jim Kupsch <[email protected]>
To: [email protected]
Date: Mon, 29 Apr 2019 16:34:00 -0000

Yes, there is no language "objective". Jim On 4/29/19 11:27 AM, Larry Golding (Myriad Consulting Inc) wrote: > 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] > > [ mailto:[email protected] ] *On Behalf Of *Larry Golding (Myriad > Consulting Inc) > *Sent:* Thursday, April 25, 2019 12:02 PM > *To:* James Kupsch <[email protected] < mailto:[email protected] >>; > [email protected] < mailto:[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 > < https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Foasis-tcs%2Fsarif-spec%2Fblob%2Fmaster%2FDocuments%2FChangeDrafts%2FAccepted%2Fsarif-v2.0-issue-376-kupsch-additional-feedback-2.docx&data=01%7C01%7Cv-lgold%40microsoft.com%7C21fb479b06294d48f95808d6ccbf2dc0%7C72f988bf86f141af91ab2d7cd011db47%7C1&sdata=o%2BDOdmMRDw5W8V%2F6ndtl3Ck8X5dReo03nEzaWG1FPRM%3D&reserved=0 > > > Larry > > *From:*Larry Golding (Myriad Consulting Inc) > *Sent:* Thursday, April 25, 2019 11:50 AM > *To:* James Kupsch <[email protected] < mailto:[email protected] >>; > [email protected] < mailto:[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] < mailto:[email protected] >> > *Sent:* Tuesday, April 16, 2019 12:49 PM > *To:* Larry Golding (Myriad Consulting Inc) <[email protected] > < mailto:[email protected] >>; [email protected] > < mailto:[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: > > 10. 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: > > 11. 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 nameand/or fullNameis part of > the product named by product, which in turn is part of the product suite > identified by productSuite. > > 12. 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.* > 13. 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:* > > 15. 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: > > 16. 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.* > 17. 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. > > 18. 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.* > 19. 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.* >