| 1 |
# Bevy's Release Notes Process |
| 2 |
|
| 3 |
Hi! Did someone add `M-Release-Note` to your PR? If so, you're in the right place. |
| 4 |
Let's talk about how this process works. |
| 5 |
|
| 6 |
When we make high-impact changes to Bevy, we need to communicate them to users (and potential users!). |
| 7 |
For the most part, this is done via our [famously in-depth release notes](https://bevy.org/news/). |
| 8 |
To avoid a crunch at the end of the cycle as we *write* all of these, |
| 9 |
Bevy asks authors (and reviewers) to write draft release notes as part of the pull requests to add high-impact features. |
| 10 |
|
| 11 |
## Where to put your release notes |
| 12 |
|
| 13 |
Each major Bevy version (e.g. 0.12, or 2.0) will get its own set of release notes. |
| 14 |
The draft release notes are organized in the `bevyengine/bevy/_release-content/release-notes` folder. |
| 15 |
|
| 16 |
When we publish our first release candidate for a cycle, these notes are merged together and moved from `bevyengine/bevy` into `bevyengine/bevy-website`, |
| 17 |
where they will receive a final editing pass and any multimedia. |
| 18 |
|
| 19 |
To start a new release note, copy-paste [the template](./release_notes_template.md) into a new file in the `release-notes` folder. |
| 20 |
|
| 21 |
## What to put in your draft release notes |
| 22 |
|
| 23 |
Release notes are intended to capture the essence of: |
| 24 |
|
| 25 |
- what has been changed or added? |
| 26 |
- why is this a big deal for users? |
| 27 |
- how can they use it? |
| 28 |
|
| 29 |
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. |
| 30 |
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. |
| 31 |
|
| 32 |
Images and videos are lovely: shiny screenshots of rendering features, diagrams, performance metrics, and cool examples are all a great choice. |
| 33 |
However, **do not put multimedia content in this folder**. |
| 34 |
We want to avoid bloating the git repo for `bevyengine/bevy`, which can cause problems for contributors (and GitHub). |
| 35 |
Instead, drop them in your PR description and we'll collect them as we're finalizing the release notes. |
| 36 |
|
| 37 |
## Grouping content into release notes |
| 38 |
|
| 39 |
Release notes should be organized by "rough feature", not "per PR". |
| 40 |
Bevy users don't care if the work was done in 17 PRs, or a single 10k line PR. |
| 41 |
|
| 42 |
As a result, each draft release note should be given a clear name matching the section title, |
| 43 |
and related PRs (and their authors!) should be collected into the metadata listed in those markdown files. |
| 44 |
|
| 45 |
If you make changes or extensions to an upcoming major feature, you should probably revise the release note for that feature. |