2021-06-02 21:07:56 +00:00
# Objective
- Describe the objective or issue this PR addresses.
- If you're fixing a specific issue, say "Fixes #X ".
## Solution
- Describe the solution used to achieve the objective above.
2022-03-16 20:48:42 +00:00
2024-05-02 00:00:00 +00:00
## Testing
- Did you test these changes? If so, how?
- Are there any parts that need more testing?
- How can other people (reviewers) test your changes? Is there anything specific they need to know?
- If relevant, what platforms did you test these changes on, and are there any important ones you can't test?
2022-03-16 20:48:42 +00:00
---
meta: Add `Showcase` section to PR template (#11750)
# Objective
Oftentimes I find myself reading through a PR and not quite
understanding what's going on. Even if it's super detailed, it can
sometimes be difficult to imagine what the end result of the PR might
look like.
For example, #10756 clearly communicates its goals and contains a
descriptive Changelog. However, I was still a bit lost as to what a user
might see from the change until I saw the dedicated example in the diff.
## Solution
At the risk of giving contributors more work, I think a dedicated
`Showcase` section could be really nice.
Along with providing reviewers stumbling on the PR with a "tangible
summary" of the change, it should also help out when working on the
release post. Sometimes someone other than the PR's author has to write
up a blog section on the PR. This can be somewhat daunting to people
wanting to contribute in that effort as they have to rely on the
Migration Guide giving a decent example (assuming it's a breaking
change), piecing together the other sections into a sensible example
themselves, or manually reading through the diff.
Theoretically, this new `Showcase` section would be more of an
encouragement than a strict requirement. And it's probably only going to
be useful where there is something to showcase (e.g. visual changes, API
changes, new features, etc.).
### Bikeshedding
- **Naming.** I also considered `Demo` and `Example`, but there may be
others we prefer. I chose `Showcase` to communicate the feeling of fun
and appreciation for the work contributors put in.
- **Position.** I placed the section right above the `Changelog` section
since I felt it made sense to move from the details in `Solution` to a
brief example in `Showcase` to a tl;dr of the changes in `Changelog`
- **Phrasing.** We can also bikeshed the bullet points and phrasing of
each as well.
2024-07-08 01:23:24 +00:00
## Showcase
2022-03-16 20:48:42 +00:00
meta: Add `Showcase` section to PR template (#11750)
# Objective
Oftentimes I find myself reading through a PR and not quite
understanding what's going on. Even if it's super detailed, it can
sometimes be difficult to imagine what the end result of the PR might
look like.
For example, #10756 clearly communicates its goals and contains a
descriptive Changelog. However, I was still a bit lost as to what a user
might see from the change until I saw the dedicated example in the diff.
## Solution
At the risk of giving contributors more work, I think a dedicated
`Showcase` section could be really nice.
Along with providing reviewers stumbling on the PR with a "tangible
summary" of the change, it should also help out when working on the
release post. Sometimes someone other than the PR's author has to write
up a blog section on the PR. This can be somewhat daunting to people
wanting to contribute in that effort as they have to rely on the
Migration Guide giving a decent example (assuming it's a breaking
change), piecing together the other sections into a sensible example
themselves, or manually reading through the diff.
Theoretically, this new `Showcase` section would be more of an
encouragement than a strict requirement. And it's probably only going to
be useful where there is something to showcase (e.g. visual changes, API
changes, new features, etc.).
### Bikeshedding
- **Naming.** I also considered `Demo` and `Example`, but there may be
others we prefer. I chose `Showcase` to communicate the feeling of fun
and appreciation for the work contributors put in.
- **Position.** I placed the section right above the `Changelog` section
since I felt it made sense to move from the details in `Solution` to a
brief example in `Showcase` to a tl;dr of the changes in `Changelog`
- **Phrasing.** We can also bikeshed the bullet points and phrasing of
each as well.
2024-07-08 01:23:24 +00:00
> This section is optional. If this PR does not include a visual change or does not add a new feature, you can delete this section.
2022-03-16 20:48:42 +00:00
meta: Add `Showcase` section to PR template (#11750)
# Objective
Oftentimes I find myself reading through a PR and not quite
understanding what's going on. Even if it's super detailed, it can
sometimes be difficult to imagine what the end result of the PR might
look like.
For example, #10756 clearly communicates its goals and contains a
descriptive Changelog. However, I was still a bit lost as to what a user
might see from the change until I saw the dedicated example in the diff.
## Solution
At the risk of giving contributors more work, I think a dedicated
`Showcase` section could be really nice.
Along with providing reviewers stumbling on the PR with a "tangible
summary" of the change, it should also help out when working on the
release post. Sometimes someone other than the PR's author has to write
up a blog section on the PR. This can be somewhat daunting to people
wanting to contribute in that effort as they have to rely on the
Migration Guide giving a decent example (assuming it's a breaking
change), piecing together the other sections into a sensible example
themselves, or manually reading through the diff.
Theoretically, this new `Showcase` section would be more of an
encouragement than a strict requirement. And it's probably only going to
be useful where there is something to showcase (e.g. visual changes, API
changes, new features, etc.).
### Bikeshedding
- **Naming.** I also considered `Demo` and `Example`, but there may be
others we prefer. I chose `Showcase` to communicate the feeling of fun
and appreciation for the work contributors put in.
- **Position.** I placed the section right above the `Changelog` section
since I felt it made sense to move from the details in `Solution` to a
brief example in `Showcase` to a tl;dr of the changes in `Changelog`
- **Phrasing.** We can also bikeshed the bullet points and phrasing of
each as well.
2024-07-08 01:23:24 +00:00
- Help others understand the result of this PR by showcasing your awesome work!
- If this PR adds a new feature or public API, consider adding a brief pseudo-code snippet of it in action
- If this PR includes a visual change, consider adding a screenshot, GIF, or video
- If you want, you could even include a before/after comparison!
- If the Migration Guide adequately covers the changes, you can delete this section
While a showcase should aim to be brief and digestible, you can use a toggleable section to save space on longer showcases:
< details >
< summary > Click to view showcase< / summary >
```rust
println!("My super cool code.");
```
< / details >
2022-03-16 20:48:42 +00:00
## Migration Guide
2022-04-16 18:57:51 +00:00
> This section is optional. If there are no breaking changes, you can delete this section.
2022-03-16 20:48:42 +00:00
- If this PR is a breaking change (relative to the last release of Bevy), describe how a user might need to migrate their code to support these changes
- Simply adding new functionality is not a breaking change.
- Fixing behavior that was definitely a bug, rather than a questionable design choice is not a breaking change.
