Migration Guide Workflow

[MinerSebas]

What problem does this solve or what need does it fill?

A clearer defined set of practices for the creation of the Migration Guides.

During the development of the 0.5 release, it became clear that the release would contain several (unintuitive) changes: #1601

The actual execution had several Problems:

1. The Issue for the Migration Guide was created relatively late in 0.5s development (~3 Months after 0.4 and ~1 Month before 0.5)
2. People were quick to report changes in the Issue, but few bothered to write them down for the Website.
3. The Website PR (Migration Guide: 0.4 to 0.5 bevy-website#107) was created by Cart targeted the ´main´ branch. This meant that other contributors send PRs to fork cart/bevy-website instead of bevyengine/bevy-website, which hurts their visibility.
4. Out of a combination of 1. and 2. not every change listed in the Issue was actually transcribed to the Website Version when 0.5 finally released. After the release, PRs were still made that added missing entries: Update _index.md bevy-website#128, More migration guide bevy-website#129, Mention system ordering behavior in 0.4-0.5 migration guide bevy-website#133

What solution would you like?

• Create a dedicated migration-guide branch on the bevyengine/bevy-website Repository. Once the next Release happens that Branch can then be merged in the main branch. This solves the Issues:
  • 1.) New entries for a new release can always be created, even if another version just released
  • 3.) bevyengine/bevy-website is more visible than a private Fork
  • and 4.).
• Add a Needs Migration Guide Lable to the bevyengine/bevy Repository, that's applied to PRs.
  • This stops the need to create a 0.x -> 0.y Migration Guide Issue for every Release.
  • A PR Author should not be required to write the Migration Guide himself, just encouraged. This shouldn't be annoying bureaucracy.

What alternative(s) have you considered?

• Do Nothing
  • The same issues mentioned above will reappear.
• Only add a migration-guide branch to bevyengine/bevy-website
  • Could be done in the short-term, until Label revamp discussed in Bevy Development Process #2256 happens.

[cart]

I love all of these ideas! I've done both of your suggestions:

• migration-guide branch: https://github.com/bevyengine/bevy-website/tree/migration-guide
• needs-migration-guide label: https://github.com/bevyengine/bevy/labels/needs-migration-guide

Thanks for putting this together.

[mockersf]

about the 0.6 release, I opened bevyengine/bevy-website#134 after the first breaking change

[cart]

Yupyup. To adapt to this I think it makes sense to change your prs base branch to migration-guide. And then we can merge into that as soon as your changes are ready.

[cart]

We might still need a centralized tracking issue to ensure things aren't dropped and ensure people don't step on each other's toes.

[cart]

But I think the per-pr tags should be considered the "source of truth".

[cart]

Also breaking changes aren't the only criteria for migration guides. I think we should also include "changes in recommended practices", such as #2398. .system() can still be used, but we should still encourage people to remove it. I just tagged that pr.