[Caching] Put caching diagnostics into its own DiagnosticGroups

[cachemeifyoucan]

Add explanation and documentation for swift caching diagnostics.

rdar://154335823

[cachemeifyoucan]

@swift-ci please smoke test

[tshortli]

This documentation explains what caching is but doesn't help the developer address the diagnostics, which I think is the primary role of documentation under userdocs/diagnostics/. I'm not necessarily saying that should be blocking, but what is the impetus for adding general documentation of caching this way?

[cachemeifyoucan]

This documentation explains what caching is but doesn't help the developer address the diagnostics, which I think is the primary role of documentation under userdocs/diagnostics/. I'm not necessarily saying that should be blocking, but what is the impetus for adding general documentation of caching this way?

It kind of says how to address the issue in a subtle way. The thought behind this is that actually the diagnostics in swift caching are mostly safe guards when something go wrong, like:

• A broken CAS/CAS Service
• User tries to modify/run the swift-frontend command-line by hand and did something unsupported
• A compiler bug

There are generally no actionable item, other than:

• Always use swift-driver to run caching build
• Delete CAS and try again

On the other hand, if hit those errors, it can be quite confusing what to do. The diagnostics are trying to provide some path forward for debugging and workaround the issue when possible. Happy to work on the wording so that it can be better for this context.

[tshortli]

It kind of says how to address the issue in a subtle way. The thought behind this is that actually the diagnostics in swift caching are mostly safe guards when something go wrong, like:

• A broken CAS/CAS Service
• User tries to modify/run the swift-frontend command-line by hand and did something unsupported
• A compiler bug

There are generally no actionable item, other than:

• Always use swift-driver to run caching build
• Delete CAS and try again

On the other hand, if hit those errors, it can be quite confusing what to do. The diagnostics are trying to provide some path forward for debugging and workaround the issue when possible. Happy to work on the wording so that it can be better for this context.

Maybe what you wrote above should be summarized in a section of the doc that is specifically about the diagnostics. For example, split it into two sections: the first being a high-level, brief overview of what caching is and the second being an explanation of potential sources of errors and what to do about them.

[cachemeifyoucan]

Document updated to be more error centric.

[tshortli]

Thanks, I think the revised version will be clearer for users!

[cachemeifyoucan]

@swift-ci please smoke test

[cachemeifyoucan]

@swift-ci please smoke test macOS platform