Add step-by-step migration guidance from classic mode to manifest mode

[Shriya-23]

Issue

• Users lack clear guidance on migrating existing projects from classic mode to manifest mode
• Baseline selection and GIT commit requirements are not clearly explained
• Existing documentation focuses on new projects only

Related issue:

• Fixes Documentation for migrating from classic mode to manifest mode #425

---

Before

• Documentation explains how to use manifest mode for new projects
• No clear steps for transitioning from classic mode
• No explanation of how to choose a builtin baseline commit
• Experimental tooling (vcpkg x-update-baseline) mentioned externally but not clarified

---

What this PR adds

• A new “Migrating from classic mode to manifest mode” section
• Clear explanation of:
  • Differences between classic and manifest mode
  • Identifying direct dependencies from classic installs
  • Selecting and pinning a builtin baseline commit
  • Enabling manifest mode safely
• Explicit notes on experimental commands and stable alternatives
• Placement directly after Prerequisites for better discoverability

---

After

• Users can migrate existing projects without guesswork
• Baseline selection is clearly explained and reproducible
• Migration steps are explicit, ordered, and non-experimental
• Documentation aligns with real-world usage and common user questions

---

• Happy to update based on feedback
• Open to expanding or simplifying steps if preferred

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

Learn Build status updates of commit d7fa45b:

✅ Validation status: passed

File	Status	Preview URL	Details
vcpkg/consume/manifest-mode.md	✅Succeeded	View

For more details, please refer to the build report.

[dg0yt]

I don't think a "migration guide" belongs into this tutorial, and in particular into this spot.

[Shriya-23]

I don't think a "migration guide" belongs into this tutorial, and in particular into this spot.

Thank you for the feedback, I really appreciate it.

I came across issue #425 and tried to contribute by adding migration guidance, since the issue was asking specifically about transitioning from classic mode to manifest mode. I placed it here because this page is often the entry point for manifest mode, so it felt like a discoverable spot for users looking to switch.

[Shriya-23]

I don't think a "migration guide" belongs into this tutorial, and in particular into this spot.

That said, I understand the concern about including migration content inside a tutorial. I’m still fairly new to contributing here, so I’d really value your guidance, if not in this spot, would you recommend moving it to a separate article or another section?

Happy to adjust the structure as needed. Thanks again for the review.