d837b9e19b
# Objective As discussed in #https://github.com/bevyengine/bevy/discussions/16431, our release process is a major bottleneck, difficult to collaborate on and a serious source of burnout (hi!). Writing all of the release notes and migration guides at the end of the cycle is miserable, and makes it harder to coalesce them across multiple PRs doing related work. ## Solution This PR largely implements the solution designed and discussed in the [Better release notes](https://discord.com/channels/691052431525675048/1331412459432710247) working group, unofficially led by @NthTensor. The [plan](https://hackmd.io/NBKkrGbbS5CaU7PsQUFGJQ) laid out in the linked HackMD has largely been folllowed, although I've also added Migration Guides too: they suffer much the same problem. I've also moved away from using the PR number as the title for the file: if we're hand-authoring the files we can do much better than that! The READMEs for each folder describe the process in more detail: please read (and comment on them!). ## Questions for reviewers / fellow implementers - I've moved away from the current "store metadata in a mega-file" approach, and moved it towards a "put the metadata in the file you're editing" design. I much prefer the locality, but it may be harder to get to play nice with our website generation. Do you want me to revert that? See [this folder](https://github.com/bevyengine/bevy-website/tree/main/release-content/0.15) for the current format. - does the "how to write release notes / migration guides" sections make sense to you here? Normally I would toss this in the Contributor's Guide, but I do like it being right beside the spot you're making changes ## Follow-up work - [ ] add a job which checks for the labels and blocks the PR if no file in the correct folder is merged - [ ] add a CI job to do basic format validation on the files inside of these folders - [ ] generate the release notes and migration guides using a modified version of [the tooling](https://github.com/bevyengine/bevy-website/tree/main/generate-release) one last time for 0.16 - [ ] remove the release notes and migration guide generating tools - [ ] build a new pipeline to turn the copy-pasted release notes here into actual website content - [ ] rethink how we're doing release notes to provide better punchy summaries for casual readers - [ ] create a CI job that checks for new or edited migration guides and automatically labels the PR --------- Co-authored-by: Joona Aalto <jondolf.dev@gmail.com> Co-authored-by: Zachary Harrold <zac@harrold.com.au> |
||
|---|---|---|
| .. | ||
| README.md | ||
| template.md | ||
Bevy's Migration Guide Process
Hi! Did someone add M-Needs-Migration-Guide to your PR? If so, you're in the right place.
Let's talk about how this process works.
When we make breaking changes to Bevy, we need to communicate them to users so their libraries and applications can be moved to the new Bevy version. To do this, we write and ship a migration guide for every major Bevy version. To avoid a crunch at the end of the cycle as we write all of these, Bevy asks authors (and reviewers) to write a draft migration guide as part of the pull requests that make breaking changes.
Where to put your migration guides
Each major Bevy version (e.g. 0.12, or 2.0) will get its own migration guide.
The draft migration guides are organized into a folder of the same name inside of bevyengine/bevy/working-migration-guides.
When we publish our first release candidate for a cycle, these notes are moved from bevyengine/bevy, and into bevyengine/bevy-website,
where they will receive a final editing pass.
What to put in your draft migration guide
A template.md file is provided in bevyengine/bevy/working-migration-guides: copy-paste that to get started!
Migration guides are intended to briefly communicate:
- what has been changed since the last release?
- why did we make this breaking change?
- how can users migrate their existing code?
Draft migration guides do not need to be polished: it's okay if you're not a native English speaker or aren't a wordsmith. Editing is easy; we just want to have an expert's view on the questions above.
When writing migration guides, prefer terse, technical language, and be sure to include terms that users might search for. Migration guides are not read end-to-end: instead, they are navigated via Ctrl+F as the reader follows the compiler errors and bugs.
Grouping changes into migration guides
Migration guides should reflect the complete experience of migrating from the last major Bevy version to the next one. If there are multiple breaking changes layered on top of each other, you should edit the existing migration guide, rather than write a new one.
While some brave users live on Bevy's main branch, we can trust them to use the draft migration guides and read the PRs in question if needed.
As a result, each draft migration should be given a clear name matching the section title. These titles should reflect the name of the old feature that was broken or changed.
Note on the #[deprecated] attribute
Rust provides a very helpful #[deprecated] attribute, which is a compiler-aware way to mark a piece of Rust code as obsolete and slated for removal.
This can be a nice a tool to ease migrations, because it downgrades errors to warnings and makes the migration information available right in the user's IDE.
However, it's not always possible to use this attribute, and Bevy does not consider it to be a substitute to a migration guide entry.