Document new process for updating changelogs#5111
Conversation
a906853 to
50e31d1
Compare
Currently, we ask that when contributors submit a pull request, they fill out a Changelog section in the description which lists all of the consumer-facing changes they've made. This section is ultimately used when creating a new release to assist with populating `CHANGELOG.md` files. However, this process is difficult to follow in practice because it forces release authors to do work on behalf of other engineers. The people that know how to describe changes best are those that made the change, so they should be reponsible for updating changelogs. With this commit, we now direct contributors to update changelog files directly as they make changes instead of placing them in the Changelog section of the PR description (which no longer exists). This commit adds documentation on how to do this effectively (much of which is now in the `contributor-docs` repo).
50e31d1 to
7ebcb93
Compare
cryptodev-2s
left a comment
There was a problem hiding this comment.
LGTM! Thanks for taking care of this.
|
|
||
| <!-- | ||
| If you're making any consumer-facing changes, list those changes here as if you were updating a changelog, using the template below as a guide. | ||
| THIS SECTION IS NO LONGER NEEDED. |
There was a problem hiding this comment.
If it's no longer needed, maybe just remove it to avoid confusion? I think the new item in the checklist below should be enough.
There was a problem hiding this comment.
Oh, do you think it would be confusing to leave this section? My observation is that over time contributors have gotten pretty good at updating this section, but only a fraction of them pay attention to the checklist. My worry is that it would be more confusing if people looked for this section and could no longer find it. So my thought was that this notice would be helpful in guiding people as they accustom to the new process. What do you see though?
There was a problem hiding this comment.
Oh and to be fair, we don't anticipate needing to keep this section around long-term. We plan on implementing a GitHub workflow soon which will enforce changelog updates via an automated PR comment (issue tracked here). Once that is in place, then we would clean up the pull request template. Does that seem like a better approach?
There was a problem hiding this comment.
Sounds good! A GitHub workflow to enforce this seems useful.
Explanation
Currently, we ask that when contributors submit a pull request, they fill out a Changelog section in the description which lists all of the consumer-facing changes they've made. This section is ultimately used when creating a new release to assist with populating
CHANGELOG.mdfiles.However, this process is difficult to follow in practice because it forces release authors to do work on behalf of other engineers. The people that know how to describe changes best are those that made the change, so they should be reponsible for updating changelogs.
With this commit, we now direct contributors to update changelog files directly as they make changes instead of placing them in the Changelog section of the PR description.
References
Closes #4385.
Checklist