[GH-ISSUE #694] Improve discoverability of changelog #2361

New issue

Closed

opened 2026-03-07 20:07:02 +03:00 by kerem · 3 comments

kerem commented

2026-03-07 20:07:02 +03:00

Owner

Originally created by @bmish on GitHub (Jan 3, 2023).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/694

Currently, there's a changelog called "History" at the bottom of the README:

https://github.com/DavidAnson/markdownlint/blob/main/README.md#history

This is lacking in discoverability when many/most repositories use a standard CHANGELOG.md file as well as GitHub releases to announce releases. These standard mechanisms have benefits like:

Easier to find
Consumable by tooling (like Dependabot which can then display the changelog in update PRs)
Can be subscribed to for updates (in the case of GitHub releases)
Maintainable by a myriad of automated release tools like release-it

What do you think?

Note: Even if you don't want to switch the format, even just including the word "changelog" somewhere could make it easier to search for it, or a table of contents at the top of the README like the one generated by this VSCode extension.

Originally created by @bmish on GitHub (Jan 3, 2023). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/694 Currently, there's a changelog called "History" at the bottom of the README: * https://github.com/DavidAnson/markdownlint/blob/main/README.md#history This is lacking in discoverability when many/most repositories use a standard `CHANGELOG.md` file as well as GitHub releases to announce releases. These standard mechanisms have benefits like: * Easier to find * Consumable by tooling (like Dependabot which can then display the changelog in update PRs) * Can be subscribed to for updates (in the case of GitHub releases) * Maintainable by a myriad of automated release tools like release-it What do you think? Note: Even if you don't want to switch the format, even just including the word "changelog" somewhere could make it easier to search for it, or a table of contents at the top of the README like the one generated by [this](https://marketplace.visualstudio.com/items?itemName=joffreykern.markdown-toc) VSCode extension.

kerem

2026-03-07 20:07:02 +03:00

closed this issue
added the
enhancement

fixed in next
labels

kerem commented

2026-03-07 20:07:03 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jan 4, 2023):

I'm fine with CHANGELOG.md (I use it for the VS Code extension), but I find GitHub Releases redundant. npm is the authority for what releases are available and what is in each; tags provide information about commits in the repo.

@DavidAnson commented on GitHub (Jan 4, 2023): I'm fine with CHANGELOG.md (I use it for the VS Code extension), but I find GitHub Releases redundant. npm is the authority for what releases are available and what is in each; tags provide information about commits in the repo.

kerem commented

2026-03-07 20:07:04 +03:00

Author

Owner

@bmish commented on GitHub (Jan 4, 2023):

Got it. I'll open up a PR for this in a moment.

@bmish commented on GitHub (Jan 4, 2023): Got it. I'll open up a PR for this in a moment.

kerem commented

2026-03-07 20:07:04 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jan 4, 2023):

Great, thank you! Please copy the content over as it is and link to it from the README. Please also add the new file to the handful of test cases that analyze Markdown files in the repository. Remember to PR against "next" branch.

@DavidAnson commented on GitHub (Jan 4, 2023): Great, thank you! Please copy the content over as it is and link to it from the README. Please also add the new file to the handful of test cases that analyze Markdown files in the repository. Remember to PR against "next" branch.