PR numbers as links in changelogs

[jthegedus]

Describe the problem

It's difficult to determine which version a merged PR is in.

I believe the changeset title is the PR title, though I am not sure this is strictly always the case.

As a maintainer of an external adapter, when I see a change to the Adapter API I often have to check the changelog of Kit (which navigating to is annoying to begin with) and read for the changesets since the last version my adapter was specifically built for. I'd rather just ctrl+f for the PR number.

Describe the proposed solution

Include PR numbers as a link to the PR in the changelog for each changeset

Alternatives considered

No response

Importance

would make my life easier

Additional Information

I imagine 1.0 will resolve most of this, though I wish to contribute to the Adapter API discussion before 1.0.

[benmccann]

We should copy the changelog script from vite-plugin-svelte https://github.com/sveltejs/vite-plugin-svelte/blob/main/scripts/changelog-github-custom.js which would fix this. Happy to accept a PR to do that

[jthegedus]

I would also add the request to this PR to add the packages with changelog links in the root README 👇

From the sveltejs/vite-plugin-svelte README

Packages

Package	changelog
@sveltejs/vite-plugin-svelte	changelog

[benmccann]

yeah, that's not a bad idea

[rmunn]

I've been able to backtrack changelog entries to PRs via commit hashes. By looking up, for example, 5911b1c7 from the 1.0.0-next.140 changelog entry, I see the commit message is "[fix] consider protocol-relative URLs as external (#2062)" and then I can look up #2062 and see the PR discussion and the linked issue.

It should be trivial to write a script to take the existing changelog with commit hashes, grab the first line of the log message for that hash, and extract a PR number from the end of that first line. As long as the commit was created using GitHub's "Squash and merge" button, the end of the commit message will be (#NNNN) where NNNN is the PR number. It's possible that not every changelog entry was made from a commit that used the "Squash and merge" button, but that method should allow backfilling PR numbers into most of the existing changelog entries, if desired.

[benmccann]

The vite-plugin-svelte script I linked to above should already handle including PR numbers in the changelog. Take a look at their changelog: https://github.com/sveltejs/vite-plugin-svelte/blob/main/packages/vite-plugin-svelte/CHANGELOG.md

[dominikg]

it won't retroactively add them though, so a one-off to sync the old entries would be good

[benmccann]

Yeah, we can just delete the old changelog and regenerate, right?

[dominikg]

I don't think it could work out the version numbers correctly, but worth a try

[rmunn]

it won't retroactively add them though, so a one-off to sync the old entries would be good

I've created #2138 to do just that. I included the script I used in #2138 (comment) so someone else can re-run it if desired (e.g., if more changesets get merged before you switch over to the changelog script from vite-plugin-svelte).

Note: #2138 doesn't include the PR numbers as links, just as #NNNN references. I figure the changelog should be kept short, as those references will be automatically turned into links when it's viewed on GitHub. But if having the actual links in the changelog file itself is desired, it should be pretty trivial to edit my script to create GitHub links and re-run it.

[benmccann]

Note: #2138 doesn't include the PR numbers as links, just as #NNNN references. I figure the changelog should be kept short, as those references will be automatically turned into links when it's viewed on GitHub. But if having the actual links in the changelog file itself is desired, it should be pretty trivial to edit my script to create GitHub links and re-run it.

I think that's only true in issues, not in files. None of the PR numbers appear to be linked: https://github.com/sveltejs/kit/blob/master/packages/kit/CHANGELOG.md

[manuel3108]

Does also do not appear with issues in my short tests.

According to this https://stackoverflow.com/questions/16539687/github-readme-reference-issue auto-referencing is only supported in issues, comments or pr, but not in pure md files

[dominikg]

github also allows linking to other issues types via https://github.com/repo/issues/NNNN
So just replacing (#NNNN) in the markdown file with ([#NNNN](https://github.com/sveltejs/kit/issues/NNNN)) via regex works.

See linkify utility of the changelog script which helps to turn text references in changesets to links.

[jthegedus]

Solution is great, thanks all! 🙏