search

microsoft / sarif-sdk

.NET code and supporting files for working with the 'Static Analysis Results Interchange Format' (SARIF, see https://github.com/oasis-tcs/sarif-spec)
Other
191 stars 90 forks source link

HDF Desc in SARIF FullDescription #2631

Closed candrews closed 1 year ago

candrews commented 1 year ago

Store HDF Desc in SARIF FullDescription, not ShortDescription.

According to https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317845

A reportingDescriptor object MAY contain a property named shortDescription whose value is a localizable multiformatMessageString object (§3.12, §3.12.2) that provides a concise description of the reporting item. The shortDescription property SHOULD be a single sentence that is understandable when visible space is limited to a single line of text.

The HDF Desc tends to be a lot longer than a single sentence, oftentimes multiple sentences, sometimes multiple paragraphs. Therefore it is more appropriate for SARIF's FullDescription, according to https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317846

A reportingDescriptor object SHOULD contain a property named fullDescription whose value is a localizable multiformatMessageString object (§3.12, §3.12.2) that comprehensively describes the reporting item.

The fullDescription property SHOULD, as far as possible, provide details sufficient to enable resolution of any problem indicated by the reporting item.

The beginning of fullDescription (for example, its first sentence) SHOULD provide a concise description of the reporting item, 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.49.9). Tools that do not construct fullDescription in this way SHOULD provide a value for shortDescription.

michaelcfanning commented 1 year ago

Hello! Thanks for this very nice change. I've added you as a write contributor. Would you mind creating a branch directly off of mine with your change (once you accept our invitation to become a contributor)?

Also, if you could add a brief description in the release notes for your change, that would be good.

Currently, our pipelines will not execute against forked contributions (as a security defense).

candrews commented 1 year ago

Hello! Thanks for this very nice change. I've added you as a write contributor.

Thank you!

Would you mind creating a branch directly off of mine with your change (once you accept our invitation to become a contributor)?

Also, if you could add a brief description in the release notes for your change, that would be good.

I've done so, here's the new PR: https://github.com/microsoft/sarif-sdk/pull/2634