# 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.
# Objective
- Reviews could go smoother if reviewers know how a PR was tested, how
they can test it, and if it needs more testing.
## Solution
- Add a testing section
# Objective
We are currently asking contributors to "skip" optional sections, which is a bit confusing. "Skip" can be taken to mean that you should "leave that section alone" and result in these bits of template being left in the PR description.
## Solution
Let contributors know that it's okay to delete the section if it's not needed.
# Objective
Context: [Discord Discussion](https://discord.com/channels/691052431525675048/745355529777315850/950532143325519902)
Improve the PR template by adding "Changelog" and "Migration Guide" sections. These sections should hopefully help speed up the review/merge process, as well as help make release notes and migration guides.
## Solution
Added the "Changelog" section template which suggests listing out the changes of the PR. This also acts as a sort of tl;dr for reviewers (especially for larger PRs).
Added the "Migration Guide" section template which suggests describing how a user might need to migrate their codebase to account for the changes by the PR. This also helps authors/contributors keep the end-user in mind when adding or changing the API.
Both sections are optional— an author does not _need_ to fill these out. Hopefully they will, though, as it provides a handful of really great benefits.
Co-authored-by: MrGVSV <49806985+MrGVSV@users.noreply.github.com>
