Document the parallel_state deprecation and its replacement

[Connor-XY]

• I, the PR author, have personally reviewed every line of this PR.

What does this PR do?

Makes the parallel_state deprecation legible from the code. Documentation only — no behavior change.

megatron.core.parallel_state holds the process groups for a single, global parallel grid, and Megatron-Core is migrating to explicit passing via ProcessGroupCollection. Nothing in the code said so:

Signal	Before this PR
"deprecat" in parallel_state.py (2692 lines)	1 hit — the DeprecationWarning on set_virtual_pipeline_model_parallel_rank, not the group accessors
"deprecat" in process_groups_config.py	0
use_mpu_process_groups docstring	"Use the default process groups from parallel_state." — reads as a feature, not a temporary shim
DeprecationWarning on any accessor	none

That gap has a cost. In #5916 a contributor replaced parallel_state.get_tensor_model_parallel_group() with ProcessGroupCollection.use_mpu_process_groups() believing it was a migration; both read the same global state, so it was a lateral move. The author had no way to know from the code.

This matters beyond tidiness. Three gradient-counting bugs — #5916 (merged), #6080, #6099 — trace to the same mechanism. #6099 states it directly: "gradient-norm duplicate filtering fell back to the global TP group, incorrectly excluding some expert parameters when ETP differed from TP."

Changes

• Mark 53 tier-1/tier-2 accessor docstrings deprecated, naming the replacement and the independent-grid failure mode.
• Module-level warning on parallel_state.py: the deprecation, the new-feature ban, the bug-fix carve-out, and that use_mpu_process_groups() is not a migration target.
• Rewrite the use_mpu_process_groups docstring to say it is a compatibility shim.
• New docs/developer/parallel-state-deprecation.md — tier table, do/don't examples, reviewer guidance — plus a section in contribute.md.

The tiering encodes @hao's guidance from #megatron-core-developments: existing usage may stay in bug fixes; new features must not use it.

Verification

AST-verified documentation-only: 99 functions before and after, and blanking every docstring makes the two trees compare equal.

One hunk is not a docstring. black 26.3.0 — the version pinned in uv.lock — wants to collapse a RankGenerator assert that already fails the check on main. The linting job runs black over every changed file, so a PR touching parallel_state.py has to carry the reformat.

Rebased onto main at 93ebf8d. The 6 GTP-remat accessors added while this was in flight (get_gtp_weight_remat_*, get_expert_gtp_weight_remat_*) are marked too, which is why the count moved from 47 to 53.

Part of #6307 — tracking issue for the parallel_state deprecation, with the landing order and what remains.

Contribution process

Pre-checks

• I have added relevant unit tests
• I have added relevant functional tests
• I have added proper typing to my code
• I have added relevant documentation
• I have run the autoformatter on my PR

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[Connor-XY]

Part of #6307 — tracking issue for the parallel_state deprecation, with the landing order, the decisions needed, and what remains.