bevyengine / bevyengine/bevy-website

Develop a Release Notes Template

Open
#1,343 0 comments 0 reactions 0 assignees View on GitHub
A-Release-Notes C-Feature E-Good-First-Issue X-Uncontroversial
Dominant language
JavaScript
Stars
249
Forks
450
Avg merge
16h 20m
Merged PRs (30d)
6

Description

# Proposal

When stubbing out new release notes, an approachable template should be provided instead of a simple `TODO`. This will help set the tone for these individual pieces for new authors, and provide a skeleton to help overcome writers block.

As an example of such a template:

````

Open with sentence providing clear context for the changes about to be described.

Follow with an example of what Bevy was like prior to this release, taking care to highlight any key differences that can illustrate why we are making this change.

Consider including example code using code blocks

```rust
use bevy::prelude::*;

fn main() {
App::new().run();
}
```

Where appropriate, [link to external information](https://bevy.org/) on related topics.

And if this change is appropriately visual, please include imagery!

![Alt text for this image](a_cool_image.png)

End with a short call to action linking to further information, and any possible related work that may come in the future.
````

I imagine the simplest way to do this automatically would be to amend the [`generate_release_notes`](https://github.com/bevyengine/bevy-website/blob/2cb5fff5c248664ae54dbb6f1ef5530e6ff9d829/generate-release/src/release_notes.rs#L86-L92) function to inject whatever starting template is appropriate. Most of the work of this issue would likely be on the creation of the template itself.

An example of previous instructions given during the creation of release notes can be found in the [0.12 announcement](https://github.com/bevyengine/bevy-website/pull/754).

## Alternatives

Perhaps including a single `Example.md`, or amending the contributors guide could also serve this purpose?

_This was originally discussed in the [0.14 release crew](https://discord.com/channels/691052431525675048/1239930965267054623/1247420149531676672) working group_

Contributor guide

Open the contributing guide

Research direction

Start in generate-release/src/release_notes.rs, especially the generate_release_notes function, to see how new release notes are stubbed. Review the linked 0.12 announcement instructions, then define the template and verify that generated release notes begin with it instead of a plain TODO.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown, rust
Domain
documentation, release
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.