Should changelog entries include a link to the corresponding PR?

[rodrigoprimo]

While helping @jrfnl prepare the changelog for the upcoming 3.2.0 release, I noticed that WPCS changelog entries don’t include links to the corresponding PRs.

We briefly discussed this, and she suggested opening an issue to gather feedback from the community.

I find links to the relevant PRs helpful when I want to learn more about a change (the reasons behind it, the discussion that led to it, and so on).

How do others feel about this? Should this be changed for future releases? Are there any downsides that I'm missing?

[dingo-d]

All for it 👍🏼

[jrfnl]

I'm generally in favour. I'm only a bit concerned about consistency as the historic changelogs won't have this information.

[rodrigoprimo]

I'm only a bit concerned about consistency as the historic changelogs won't have this information.

From my perspective, it is better to include links in changelog entries from now on rather than not include them to maintain consistency with the changelog for older versions.

Since all the maintainers have expressed their opinion and this issue has been open for a couple of weeks, do we have enough to make a decision, or should we leave this issue open for a bit more?

[jrfnl]

I haven't seen an opinion from @GaryJones yet.

I would also like to point out that this practice does make doing the actual release more involved and more error prone.

In my experience, the markdown parsing for the /releases/ page is not always the same as the markdown parsing for the pages for individual releases.
In practice, this means that the use of "link lists" (i.e. use simplified link markers inline in Markdown text and have the full links in a list at the bottom of the section/document) will work in one, but not in the other (in most projects, I've seen exception too 😵).

The implications of this are that we can't just copy/paste the changelog to the release anymore, but that all links using link lists will need to be changed to inline links just and only for the release notification.

Just mentioning this to make sure people are aware of the consequences of changing this practice.

[GaryJones]

I haven't seen an opinion from @GaryJones yet.

I'd given a thumbs-up on the original message.

My approach recently for other package releases:

• Start to create release notes in GitHub. Use the "Generate release notes" feature.
• Copy the "What's Changed" into a changelog, and re-order into KeepAChangelog sections. Adjust with any extra highlight notes as needed (like minimum PHP and WP requirements)
• After pushing a tag, paste the resulting formatted changes back into the GitHub release notes, adjusting the heading levels by one. Keep the "New Contributors" section that was automatically generated.
  Example changelog. Example release notes.

[jrfnl]

I'm definitely very much against using the GitHub "generate release notes" feature. That just gathers titles from PRs and those are intended for maintainers (who actually know the codebase well) and often are pretty crappy anyway.

In my opinion, changelogs should be for humans, not for machines.

[jrfnl]

I'd like to suggest closing this as the 3.2.0 release will contain the PR links.

[rodrigoprimo]

Thanks for including the links on the 3.2.0 changelog, @jrfnl. I will close this issue.