docs: some work on the migrade / upgration guide

[goto-bus-stop]

This is not meant to "complete" the guide, just to group and expand the guidance to make it useful enough for dogfooding.

In this "first round" of work, I'm aiming to:

• Make the individual items more useful to people (clearly say what has changed and why it's better for you; clearly say what you need to do)
• Introduce a rough grouping of items (this is not necessarily meant as the final state: just to start off with something that can be more easily iterated on)

Drafting as neither item is complete.

[svc-apollo-docs]

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 1 changed, 0 removed

* graphos/reference/upgrade/from-router-v1.mdx

Build ID: 55bc98af94e9ef76c40b5016

URL: https://www.apollographql.com/docs/deploy-preview/55bc98af94e9ef76c40b5016

[goto-bus-stop]

I hope our docs system supports this. I think diff syntax would be the best way to show certain config changes.

[goto-bus-stop]

Using normal yaml with comments instead for now.

[shorgi]

@goto-bus-stop - I copyedited the entries and reorganized them under new headings:

• Removals and deprecations
• Configuration changes
• Functionality changes
• New capabilities

Rather than spread the breaking changes under separate functionality-specific headings (e.g. telemetry, customizations, etc.), I wanted to present them at the top of the guide. That lead me to have Removals and deprecations first, then configuration and functionality changes. The New capabilities captures the new features that don't necessarily have breaking changes but we want to highlight and recommend.

Still have copyediting and perhaps some finer categorization within each heading. (The docs team has also discussed adding flags/labels/shields to categorize content. We haven't gotten around to implementing them, but this would be a great use-case in the near future.)

[goto-bus-stop]

Yes this is great! We used the new organisation during a trial run of the in-house upgrade and it worked quite well.

We also noted some points that would be useful to add to the guide, which i'll do some first drafts off today.