Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add link reference definitions to CHANGELOG.md #2746

Merged
merged 1 commit into from
May 10, 2021

Conversation

foresterre
Copy link
Contributor

@foresterre foresterre commented May 3, 2021

Description

The changelog of rustup already contained link labels, but did not contain matching link reference definitions. This commit adds matching link reference definitions for all previous releases. The link reference definitions point to the diff of two releases, except for the first release in the changelog, which points to the release tag. This allows markdown viewers, to show clickable links to the diff for each release.

Preview of changes

Previously, the link labels looked like this:

[1.24.1] - 2021-04-27

with the markdown definition:

## [1.24.1] - 2021-04-27

Using this commit, the link labels look like this:

1.24.0 - 2021-04-27

with the markdown definition:

## [1.24.0] - 2021-04-27

...

[1.24.0]: https://github.com/rust-lang/rustup/compare/1.23.1...1.24.0

@kinnison
Copy link
Contributor

kinnison commented May 3, 2021

I think the square brackets were stylistic rather than meant to be link points, however I'm not entirely averse to this idea. I will note that almost always that delta will be near impossible for someone to read usefully though. @rbtcollins If you think this is "not insane" to do then please merge. There's no need to fire the actions since none of them consume the changelog.

@rbtcollins
Copy link
Contributor

Interesting idea. Uh, I think its probably unlikely to be useful for people to read such a diff - but perhaps it is for you - what prompted this patch?

Thanks

@foresterre
Copy link
Contributor Author

Sometimes I need to search for a specific change I read about in the changelog and use these (links to the) diffs to search for the specific commit in which the described change was made.

Yesterday, I went through the rustup changelog for something similar (issues #2717 and #2748) and thought, hey, the link definitions are missing, let me add those while waiting for a build 😜. I thought I recognized the format as similar to keep a changelog.

@rbtcollins
Copy link
Contributor

I'm torn, I support giving folk information, but I'm not sure how useful it will be: we have lots of bugs that look similar but are distinct, and we strongly prefer that folk file new bugs unless they are hitting one of the few bugs we've escalated to a general-problem status (and pinned / gardened to make super clear).

@kinnison
Copy link
Contributor

kinnison commented May 8, 2021

Sometimes I need to search for a specific change I read about in the changelog

We link to the PRs whenever we talk about a change normally. If we're failing to do that then we should fix that.

My gut feeling is that these links simply won't be useful for more than a very small number of people and will likely confuse others more. I'd be fine with linking to the tag page instead - https://github.com/rust-lang/rustup/releases/tag/1.24.1 for example - which has a compare button if someone wishes to use it.

@foresterre foresterre force-pushed the fix-changelog-links branch from 1bbe138 to a1d0aa7 Compare May 10, 2021 03:48
The changelog of rustup already contained link labels, but did not contain matching link reference definitions. This commit adds matching link reference definitions for all previous releases. The link reference definitions point to GitHub release page for each tag.
@foresterre foresterre force-pushed the fix-changelog-links branch from a1d0aa7 to d24f5e0 Compare May 10, 2021 03:51
@foresterre
Copy link
Contributor Author

Sometimes I need to search for a specific change I read about in the changelog

We link to the PRs whenever we talk about a change normally. If we're failing to do that then we should fix that.

My apologies, they are there indeed, I don't understand how I missed these links.

I'd be fine with linking to the tag page instead - https://github.com/rust-lang/rustup/releases/tag/1.24.1 for example - which has a compare button if someone wishes to use it.

I updated the links to point to the tag release pages instead of the diffs.

@kinnison
Copy link
Contributor

OK cool, this looks good. Thank you. I shall endeavour to do similarly on future releases :D

@kinnison kinnison merged commit 7d8b14d into rust-lang:master May 10, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants