Currently, we ask that when contributors submit a PR, they add changelog entries within the description of that PR. When a new release PR is created, the manager of the release then copies over the various changelog entries from the PRs involved in that release to various changelogs.

This process is problematic for a few reasons:

1. Reviewers are used to using the PR description to understand the context behind the changes; they are not used to reviewing changelog entries there.
2. If a reviewer wants to leave a suggestion for a changelog entry, it is awkward to do so in a comment on the Conversation tab. It would be more natural to attach that suggestion to a line on the Changes tab (the diff view).
3. When preparing a release PR, it's a pain to go back through each PR to copy the changelog entries from the description into the final changelog. It would be easier to assume that they are in the correct form by the time that a release PR is created.

Putting this together, changelog entries often get missed in reviews, so in preparing a release PR, the release manager must spend time gathering context about PRs they may not have created themselves in order to reword them appropriately. Ideally, the team who introduced the change are the best people to describe that change in the changelog, and the time during which a change is being introduced is the best time to update the changelog.

To fix this, we can ask that contributors update changelogs in their PRs. However, we have another problem, which is that people still don't quite know how to do this (we find we have to make all kinds of corrections in release PRs). We should not only communicate the new process but also provide a better guide for filling out changelogs than what we have today.

Acceptance Criteria

• Contributors have up to date instructions in the pull request template on updating changelogs.
  • The pull request template no longer contains the Changelog section and instead has a new item in the checklist at the end that reminds contributors to update the changelog in the PR.
• Contributors have a clearer picture of how to update changelogs so that they clearly communicate API changes and make it easy for other engineers to upgrade a package to new major versions without needing to dive into PRs for more context.
  • Right now we have a little section on this in the "Releasing changes" section in the Contributing doc. I think we should extract that to a separate document at least so it's more visible.
  • If we have more time we can expound upon the existing steps, but we don't have to put too much work into it. I think providing some examples of good and not-so-good entries would probably make the biggest impact here. Mainly, changes to the API should be crystal clear (and types are part of the API too). If I'm an engineer and I'm upgrading a package, and I need to add a new argument to a constructor or pass a new argument to a function or whatever, I want to know what that is just from reading the changelog entry.
• Contributors can consult documentation on the new process for updating changelogs alongside changes.
  • The best place for this might be the "Creating pull requests" in the Contributing doc. Currently this just asks people to fill out the PR description appropriately and specifically mentions the Changelog section in the pull request template. We can remove that second bullet point, simplify wording to focus specifically on filling out the Explanation section, and then we can add a new paragraph that reminds people to document their changes in the changelogs for the packages they've changed. We can link to the new document we created in the previous step.
• Contributors are aware of the new changes
  • We should make a new announcement in Slack informing people of the new process.