0a2e183476
# Objective This PR begins integrating the new releate-content drafting process (https://github.com/bevyengine/bevy/pull/18427) into our GitHub workflows. It's similar to what we had before: Messages are posted to PRs tagged with `M-Needs-Release-Note` or `M-Needs-Migration-Guide` asking them to add the required material and linking to the instructions. These messages do not trigger if the PR already has modified files in the `release-notes` or `migration-guides` directories (respectively). I have also re-arranged and content slightly (to remove the need for a directory with the current version number), tweaked the language, and switched the templates to use the [standard markdown frontmatter format](https://jekyllrb.com/docs/front-matter/). ## Reviewer Questions + Do we want to add a CI rule actually requiring tagged PRs to create/modify files in the correct directories, or is the message prompt enough? + Do we want to add a CI rule to lint the metadata, for example to enforce that the PR number is included in the files it modifies?
2.5 KiB
Bevy's Release Notes Process
Hi! Did someone add M-Needs-Release-Note to your PR? If so, you're in the right place.
Let's talk about how this process works.
When we make high-impact changes to Bevy, we need to communicate them to users (and potential users!). For the most part, this is done via our famously in-depth release notes. To avoid a crunch at the end of the cycle as we write all of these, Bevy asks authors (and reviewers) to write draft release notes as part of the pull requests to add high-impact features.
Where to put your release notes
Each major Bevy version (e.g. 0.12, or 2.0) will get its own set of release notes.
The draft release notes are organized in the bevyengine/bevy/release-content/release-notes folder.
When we publish our first release candidate for a cycle, these notes are merged together and moved from bevyengine/bevy into bevyengine/bevy-website,
where they will receive a final editing pass and any multimedia.
To start a new release note, copy-paste the template into a new file in the release-notes folder.
What to put in your draft release notes
Release notes are intended to capture the essence of:
- what has been changed or added?
- why is this a big deal for users?
- how can they use it?
Draft release notes 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: as someone with the expertise needed to implement an awesome feature we want a rough expert's perspective that we can shape into something that reads smoothly and has a consistent voice.
Images and videos are lovely: shiny screenshots of rendering features, diagrams, performance metrics, and cool examples are all a great choice.
However, do not put multimedia content in this folder.
We want to avoid bloating the git repo for bevyengine/bevy, which can cause problems for contributors (and GitHub).
Instead, drop them in your PR description and we'll collect them as we're finalizing the release notes.
Grouping content into release notes
Release notes should be organized by "rough feature", not "per PR". Bevy users don't care if the work was done in 17 PRs, or a single 10k line PR.
As a result, each draft release note should be given a clear name matching the section title, and related PRs (and their authors!) should be collected into the metadata listed in those markdown files.
If you make changes or extensions to an upcoming major feature, you should probably revise the release note for that feature.