sarif-support-for-code-scanning should explain how each field is surfaced

[jsoref]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning

What part(s) of the article would you like to see updated?

For each item documented in this page, there should be an indication of how a user will see the field.

Additional information

I'm currently using "help.text" : "?" and I have yet to discover where this field is surfaced even though the help says:

Required. Documentation for the rule using text format. Code scanning displays this help documentation next to the associated results.

[cmwilson21]

👋 @jsoref Thanks so much for opening an issue! I'll triage this for the team to take a look 👀

[felicitymay]

Hi @jsoref - thanks for opening this issue. You're right. We did intend to describe how each field was surfaced but it sounds as if there may be some changes needed here.

I'm wondering if you have a SARIF file that you've been using for testing this that you're able to share?

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

[jsoref]

One is available as an artifact here: https://github.com/jsoref/retrobot/actions/runs/3141644977

I don't really have one, as I'm iterating my tooling as I go. But, they're more or less all the same. I'm still deciding how things should work, e.g. should I omit rules that are not used by a report? I'm leaning towards doing that, but I haven't yet. And I'm also trying to decide if I should make it easy to dynamically update the descriptions as people don't tend to update my action/workflow terribly quickly and as the descriptions are roughly equivalent to documentation, which in the case of docs.github.com can update independently of the GitHub actions (whether it's GitHub/codeql itself or actions/*).

It'd be nice if there were best practices to answer questions like this...

[felicitymay]

Thanks for sharing your artifact ✨

It'd be nice if there were best practices to answer questions like this...

That's a good point.

The new sections from Providing data to track code scanning alerts across runs to "Validating your SARIF file" were added to give guidelines for common problems that people have run into while creating third-party applications.

Clearly there is still room for improvement 🙂

[jsoref]

Fwiw, there are some whitespace issues with the examples at the bottom, missing commas and literally odd numbers of spaces for indenting at times.

[github-actions]

This is a gentle bump for the docs team that this issue is waiting for technical review.