docs: Add "Coverage with test sharding" section to test.mdx

[Affanmir]

What this PR does

Adds a new "Coverage with test sharding" subsection to the Python test goal docs, covering the complete workflow for getting accurate combined coverage when using pants test --shard=N/T.

Why this is needed

The --shard flag is a common pattern for speeding up CI by splitting tests across parallel runners. However, the existing docs cover coverage and parallelism/batching in isolation — there is no guidance on what happens to coverage when sharding is in use.

The problem: each shard only exercises ~1/N of test targets, so the per-shard coverage report is artificially low (e.g. ~50% of actual coverage with 2 shards). Without knowing to combine the binary .coverage files, users will either:

• See misleadingly low coverage numbers and disable coverage, or
• Have fail_under fire on every shard and give up on sharding.

What's documented

A four-step workflow:

1. Generate binary data — add "raw" to [coverage-py].report so Pants writes the .coverage binary alongside XML.
2. relative_files = true — required in .coveragerc because each shard runs in its own sandbox; relative paths let coverage combine match files across sandbox directories.
3. Upload dotfiles — actions/upload-artifact silently drops dotfiles by default; set include-hidden-files: true to capture .coverage.
4. Post-shard combine job — download all shard artifacts, copy .coverage binaries to the repo root, run coverage combine, generate final XML, and enforce fail_under only at this point.

Two admonitions call out the two most common gotchas:

• Don't set fail_under in pants.ci.toml when sharding (fires prematurely on every shard)
• global_report = true produces misleading per-shard zeroes; apply it post-merge instead

Checklist

• Added new ### Coverage with test sharding subsection in the Coverage section of docs/docs/python/goals/test.mdx
• Placement: after the fail_under / --test-open-coverage paragraphs, before ## JUnit XML results
• All code blocks closed, admonitions use :::caution / :::note syntax
• No changes to any other files

[benjyw]

Hi, thanks for this, it is a great addition to the docs, but I think it could use some rephrasing.

The first two "steps" aren't really steps, they're one-time config. And then the other two steps are specific to github actions.

So I recommend showing the config needed, and then just saying that you need to merge the coverage reports, and give the github actions workflow as an example of how to do this.

[benjyw]

Looks good, and will be useful for folks. Thanks!