MetaMask / core

This monorepo is a collection of packages used across multiple MetaMask clients
MIT License
287 stars 185 forks source link

Introduce new process for entering changelog entries prior to release PR #4385

Open mcmire opened 4 months ago

mcmire commented 4 months ago

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

MajorLift commented 3 months ago

Is there anything keeping us from applying this practice as standard to all repos that rely on auto-changelog and the create-release-pr action? If not, would it be better to move docs/reviewing-release-prs.md and the documentation articles proposed in this ticket into contributor-docs?

desi commented 1 month ago

We need documentation, update the PR template to include this in the check list, make a general announcement about this and push back on PRs that aren't doing this.