[BREAKING][megatron] chore: deprecate vanilla mBridge and make Megatron Bridge default

[HollowMan6]

What does this PR do?

Add vanilla mBridge deprecation warning and make Megatron Bridge default.

Checklist Before Starting

• Search for similar PRs. Paste at least one query link here: ...
• Format the PR title as [{modules}] {type}: {description} (This will be checked by the CI)
  • {modules} include fsdp, megatron, veomni, sglang, vllm, rollout, trainer, ci, training_utils, recipe, hardware, deployment, ray, worker, single_controller, misc, perf, model, algo, env, tool, ckpt, doc, data, cfg, reward, fully_async, one_step_off
  • If this PR involves multiple modules, separate them with , like [megatron, fsdp, doc]
  • {type} is in feat, fix, refactor, chore, test
  • If this PR breaks any API (CLI arguments, config, function signature, etc.), add [BREAKING] to the beginning of the title.
  • Example: [BREAKING][fsdp, megatron] feat: dynamic batching

Test

For changes that can not be tested by CI (e.g., algorithm implementation, new model support), validate by experiment(s) and show results like training curve plots, evaluation results, etc.

API and Usage Example

Demonstrate how the API changes if any, and provide usage example(s) if possible.

# Add code snippet or script demonstrating how to use this

Design & Code Changes

Demonstrate the high-level design if this PR is complex, and list the specific changes.

Checklist Before Submitting

Important

Please check all the following items before requesting a review, otherwise the reviewer might deprioritize this PR for review.

• Read the Contribute Guide.
• Apply pre-commit checks: pre-commit install && pre-commit run --all-files --show-diff-on-failure --color=always
• Add / Update the documentation.
• Add unit or end-to-end test(s) to the CI workflow to cover all the code. If not feasible, explain why: ...
• Once your PR is ready for CI, send a message in the ci-request channel in the verl Slack workspace. (If not accessible, please try the Feishu group (飞书群).)
• If your PR is related to the recipe submodule, please also update the reference to the submodule commit via git submodule update --remote or cd recipe && git pull origin main.

[gemini-code-assist]

Code Review

This pull request transitions the default Megatron checkpointing backend from the legacy mbridge to the official Megatron-Bridge (v0.5.0). It updates various Dockerfiles, documentation, and configuration files to set vanilla_mbridge to False by default, while raising a deprecation warning when the legacy backend is explicitly enabled. The review feedback suggests pinning the megatron-bridge dependency to ==0.5.0 in the stable SGLang and vLLM Dockerfiles to ensure build reproducibility, and recommends using FutureWarning instead of DeprecationWarning so that end-users are properly alerted to the deprecation.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Copilot]

Pull request overview

This PR makes Megatron-Bridge the default backend for Megatron “bridge” weight conversion/checkpoint flows, while marking the legacy mbridge backend as deprecated and updating configs/docs/CI and container images accordingly.

Changes:

• Flip vanilla_mbridge defaults to False for Megatron configs and generated trainer config; add a deprecation warning when opting into legacy mbridge.
• Keep MindSpeed on legacy mbridge explicitly and document the behavior in config files and docs.
• Add megatron-bridge to the mcore extra and install it in relevant Docker images; update CI/e2e workflow env defaults.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
verl/workers/config/engine.py	Change default vanilla_mbridge to False; emit a warning when legacy backend is selected; keep MindSpeed on legacy backend.
verl/trainer/config/ref/megatron_ref.yaml	Update ref default for vanilla_mbridge to False.
verl/trainer/config/engine/mindspeed.yaml	Explicitly set vanilla_mbridge: True for MindSpeed.
verl/trainer/config/engine/megatron.yaml	Update default vanilla_mbridge to False and document deprecation.
verl/trainer/config/_generated_ppo_megatron_trainer.yaml	Regenerate config to reflect new vanilla_mbridge defaults (false).
verl/models/mcore/readme.md	Update integration notes to reflect Megatron-Bridge as default and mbridge as deprecated.
setup.py	Add megatron-bridge alongside mbridge in the mcore extra.
docs/perf/best_practices.rst	Update parameter reference to describe Megatron-Bridge as default and mbridge as deprecated.
docs/ascend_tutorial/dev_guide/model_dev/parameter_and_metrics.md	Update Chinese parameter table defaults/wording to match new defaults.
docker/rocm/README.md	Document Megatron-Bridge in ROCm image contents.
docker/rocm/Dockerfile.rocm	Install megatron-bridge==0.5.0 in ROCm build.
docker/Dockerfile.stable.vllm	Install Megatron-Bridge in stable vLLM image.
docker/Dockerfile.stable.trtllm	Bump Megatron-Bridge pin to 0.5.0 in TRTLLM image.
docker/Dockerfile.stable.sglang	Install Megatron-Bridge in stable SGLang image.
.github/workflows/e2e_ppo_trainer_megatron_vllm_rocm.yml	Switch e2e runs to VANILLA_MBRIDGE=False / VALUE_VANILLA_MBRIDGE=False.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gemini-code-assist]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

[gemini-code-assist]

Code Review

This pull request updates the default model-weight backend for Megatron-Core from the legacy, deprecated mbridge to the official Megatron-Bridge (version 0.5.0). It updates Dockerfiles, documentation, configuration files, and adds deprecation warnings when the legacy backend is selected. Feedback on this PR suggests specifying a minimum version constraint of >=0.5.0 for megatron-bridge in setup.py to prevent users from installing older, incompatible versions.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[HollowMan6]

/gemini review

[gemini-code-assist]

Code Review

This pull request transitions the default model-weight backend for Megatron from the legacy mbridge to the official Megatron-Bridge (version 0.5.0). It updates Dockerfiles, documentation, configuration files, and setup.py to reflect this change, setting vanilla_mbridge to False by default while deprecating the legacy mbridge backend with a warning. The review feedback suggests two key improvements: first, the deprecation warning for vanilla_mbridge should only be triggered when use_mbridge is enabled to avoid confusing warnings; second, a minimum version constraint (>=0.5.0) for megatron-bridge should be specified in setup.py to guarantee compatibility.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.