mirror of
https://github.com/bevyengine/bevy
synced 2024-11-22 04:33:37 +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.
This commit is contained in:
parent
b30b0a731c
commit
2968d4121b
2 changed files with 25 additions and 7 deletions
8
.github/linters/.markdown-lint.yml
vendored
8
.github/linters/.markdown-lint.yml
vendored
|
@ -1,3 +1,9 @@
|
|||
{
|
||||
"MD013": false
|
||||
"MD013": false,
|
||||
"no-inline-html": {
|
||||
"allowed_elements": [
|
||||
"details",
|
||||
"summary"
|
||||
]
|
||||
}
|
||||
}
|
24
.github/pull_request_template.md
vendored
24
.github/pull_request_template.md
vendored
|
@ -16,14 +16,26 @@
|
|||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
## Showcase
|
||||
|
||||
> This section is optional. If this was a trivial fix, or has no externally-visible impact, you can delete this section.
|
||||
> 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.
|
||||
|
||||
- What changed as a result of this PR?
|
||||
- If applicable, organize changes under "Added", "Changed", or "Fixed" sub-headings
|
||||
- Stick to one or two sentences. If more detail is needed for a particular change, consider adding it to the "Solution" section
|
||||
- If you can't summarize the work, your change may be unreasonably large / unrelated. Consider splitting your PR to make it easier to review and merge!
|
||||
- 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>
|
||||
|
||||
## Migration Guide
|
||||
|
||||
|
|
Loading…
Reference in a new issue