[ANE-2616] Snippet Scan docs

[spatten]

Overview

Delivers ANE-2616

This PR updates the documentation for fossa analyze --x-snippet-scan

1. Move most of the documentation out of docs/references/subcommands/analyze.md and into docs/features/snippet-scanning.md. The subcommand documentation links to the feature documentation.
2. Add a section talking about scan speeds and how they get faster the second time you scan something
3. Add a note about how you need a feature flag switched on to use this
4. Add a section describing the snippet scan summary
5. Link to the snippet scan summary documentation from the snippet scan in the CLI output

Links to rendered files:

• docs/featured/snippet-scanning.md
• docs/references/subcommands/analyze.md

Acceptance criteria

• The documentation is clear
• The link to the snippet scan documentation after the summary is correct

Testing plan

This is mostly documentation, but I tested that the new link at the end of the snippet scan summary is correct.

Follow the testing plan for #1613. The link at the bottom of the snippet scan summary will look like this:

  ============================================================
  Snippet scan summary:
    Analysis ID: 122839
    Bucket ID: 123373
    Files skipped: 6
    Total Files processed: 18
    Unique Files processed: 13
    Unique Files with matches found: 4
    Unique Files with no matches found: 9
    Unique Files already in our knowledge base: 13
    Unique Files new to our knowledge base: 0
    Processing time: 7.776s
  ============================================================
  See the docs for an explanation of this summary: https://github.com/fossas/fossa-cli/blob/master/docs/features/snippet-scanning.md#the-snippet-scan-summary

That link won't work right now, but it will once this is merged and on master. So change the tag from master to 116ab36adc153ea76745517092976da4cff92d14 and check that it works

https://github.com/fossas/fossa-cli/blob/cfd041bbcd7ad2126b7a83a95f4394bd4a093ba1/docs/features/snippet-scanning.md#the-snippet-scan-summary

Risks

Metrics

References

Checklist

• I added tests for this PR's change (or explained in the PR description why tests don't make sense).
• If this PR introduced a user-visible change, I added documentation into docs/.
• If this PR added docs, I added links as appropriate to the user manual's ToC in docs/README.ms and gave consideration to how discoverable or not my documentation is.
• If this change is externally visible, I updated Changelog.md. If this PR did not mark a release, I added my changes into an ## Unreleased section at the top.
• If I made changes to .fossa.yml or fossa-deps.{json.yml}, I updated docs/references/files/*.schema.json AND I have updated example files used by fossa init command. You may also need to update these if you have added/removed new dependency type (e.g. pip) or analysis target type (e.g. poetry).
• If I made changes to a subcommand's options, I updated docs/references/subcommands/<subcommand>.md.

[csasarak]

Looks good, I mostly left questions.

One thing I'd like to see is if you could add this and some of its sections to the main manual ToC: https://github.com/fossas/fossa-cli/blob/master/docs/README.md

In lieu of an mdbook setup, I've been trying to keep a mostly flat list of topics for folks. It's hard to know what you don't know and that index is meant to help address that.

[csasarak]

Is there a simple way to verify that it is enabled? It may be good to describe that if so.

[spatten]

Not that I can think of, unfortunately. I'm going to just leave this and maybe we can fix it if it turns out to be a problem in the future

[csasarak]

Can you characterize temporarily a bit more? Is this optional? If I were a customer reading this I'd want more details since the idea that you're uploading source code could be a bit alarming.

[csasarak]

Ah, I see that you wrote about it more down below. Maybe reference that section here for people like me who freak out before reading the whole doc?

[spatten]

Good point. Done!

[csasarak]

Is this last sentence meant to contrast snippet filtering with our currently existing ones?

[csasarak]

Should we recommend running an initial manual scan to "prime" before turning this on in CI?

I could see someone naively just turning this on in CI and having a ton of jobs (due to multiple simultaneous pushes/revisions) all start doing the full-scan. I think that'd be bad for Sparkle and also a poor experience for the customer.

[csasarak]

Hmm, maybe a future future version of this (if it's a problem at all) could use content to know if two scans are basically the same and then only let one of them proceed while the others just wait.

[spatten]

I like the idea of recommending that they do an initial scan. I think this takes care of 99% of the problem, as those hypothetical parallel scans will then do almost no work

[csasarak]

It may be worth communicating this to support as well.

[spatten]

Yes, that's a good point. I'll mention it in the support and snippet scanning channel