Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

HDF Desc in SARIF FullDescription #2634

Merged
merged 2 commits into from
Mar 7, 2023
Merged

Conversation

candrews
Copy link
Collaborator

@candrews candrews commented Mar 3, 2023

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.

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.
@candrews
Copy link
Collaborator Author

candrews commented Mar 7, 2023

@michaelcfanning how does this PR look?

I'm eager to get this merged and see the improvement in a release :-)

@michaelcfanning michaelcfanning enabled auto-merge (squash) March 7, 2023 17:28
@michaelcfanning michaelcfanning merged commit 4f5b49f into main Mar 7, 2023
@michaelcfanning michaelcfanning deleted the hdf-sarif-FullDescription branch March 7, 2023 17:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants