Migration guide TOC design

[StephenBonikowsky]

The intent for this TOC is to display migration data and information in a logical structure that mimics what we believe is the most common migration path. We hope this does 2 things...

1. Documentation is easier to find.
2. The layout of the information itself provides an overview of the entire migration process.

This TOC is a "living" doc meaning that it is not static and complete as is, but if done correctly it should be obvious and easy to see where new content should be plugged in.

Please provide feedback and recommendations for needed content in the comments.

Phase 1 is the minimal set of initial changes needed to map existing content to the new TOC structure. Once the Phase 1 plan has been approved, issues will be opened for the needed work and assigned.

Please do not edit the TOC directly, provide your feedback via comments.

For more about this overall effort: Migration Guide Documentation Revamp Project tracking this effort: Migration Guide Project

---

• [ ] Migration Guide

  • [ ] Overview (#25237)
  • [ ] General Information
  • [ ] .NET Overview (#25240)
  • [ ] .NET Framework, .NET Standard & .NET Core (#25239)
  • [ ] Compatibility and Breaking Changes (#25241)
  • [ ] .NET Releases and Servicing Support (#25242)
  • [x] Versioning relationship between the .NET SDK, MSBuild and VS [#24568 - Phase 1]
  • [x] Choose between .NET 5 and .NET Framework for server apps [#24582 - Phase 1]
  • [ ] Windows to Cross Platform (#25245)
  • [ ] Reasons for Porting (#25246)
  • [x] .NET Upgrade Assistant tool [#24561 - Phase 1]
    • [x] Overview
    • [x] Windows Presentation Foundation
    • [x] Windows Forms
    • [x] ASP.NET Core
  • [ ] Recommended Blogs (#25247)
  • [ ] Case Studies (#25248)

• [ ] Pre-Migration

  • [ ] Asses the portability of your project
  • [ ] Overview (#25249)
  • [ ] Visual Basic Considerations (#25251)
  • [x] Unsupported dependencies [#24567 - Phase 1]
  • [x] Dependency on Windows APIs [#24576 - Phase 1]
  • [x] Unavailable technologies [#24575 Phase 1] Phase 2: Add VB Razor story
  • [x] Unsupported APIs [#24570 - Phase 1] -Feature re-writes
  • [ ] Needed changes before porting code (#25252)
  • [ ] Create a porting plan (#25253)
  • [ ] Overview
    • What TFM should you be targeting?
  • [ ] Approaches
  • [ ] Project structure
  • [ ] .NET Framework compatibility mode
  • [ ] Testing strategy
  • [ ] Deployment considerations

• [ ] Migration

  • [ ] Overview
  • [ ] Simple changes first
    • Overview
    • Roslyn analyzers & code fixers
    • Known 1to1 API mappings
  • [ ] Unavailable technologies
    • Overview
    • List of unavailable technologies with replacement recommendations and links to guides
  • [ ] Application Porting Guides
  • [ ] Overview
  • [ ] WebAPI/ASP.NET
    • [ ] Add VB Razor story
  • [ ] Windows Forms [#24578 - Phase 1]
  • [ ] Windows Presentation Foundation [#24579 - Phase 1]
  • [ ] C++/CLI [#24580 - Phase 1]
  • [ ] WCF
  • [ ] Packaging
  • [ ] Overview
  • [ ] Producing your own packages
  • [ ] Consuming other's packages

• [ ] Post-Migration

  • [ ] Overview
  • [ ] Deployment
    • Leverage Existing Deployment Docs (page content)
    • Add content learned from 1st and 3d party migration experiences
    • Implications of Breaking Changes on deployment scenarios such as roll forwarding
  • [ ] Servicing updates
    • Leverage any existing content
    • Add content learned from 1st and 3d party migration experiences
  • [ ] Moving to latest
    • Leverage existing content such as NET Core Releases and Support

[Pilchie]

Note - Winforms shouldn't have significant challenges in migration that require re-writing.

[KathleenDollard]

Can we have a section, probably under Pre-Migration Analyze and Asses that is something like "Visual Basic Considerations". I'd like a TOC level entry that helps VB folks make the decision. That would give me some context for words :)

Also, in the Analyze and Assess section, I don't see anything on LTS and servicing. There is a pretty massive difference between "As long as Windows lives" and 3 months or 1 year after next release. For some companies that will be a big factor in a decision.

[StephenBonikowsky]

@KathleenDollard thanks for the feedback! I added "Visual Basic Considerations".

There is some great info already out there in blogs and such (@jamshedd) regarding .NET releases, the cadence, the support story, etc...I added a place under General Info --> About .NET for that, and then under Migration --> Create a porting plan, I added a bullet point to address the question of what TFM should be targeted which could refernce back to the main page with all the release and servicing info. This would also be a great place to reference Immo's blog The Future of .NET Standard