Docusaurus: project: A CHANGELOG.md success story

[tony]

More and more projects have been migrating away from CHANGES files in favor of GitHub Releases.

Docusaurus' CHANGELOG.md:

• One file

• Markdown

• Sync'd with git tags

  Example: v2.0.0-beta.13

• Easily linkable to headers

  Linking to v2.0.0-beta10

• Includes date

  Bonus, date shows in headers: CHANGELOG.md#200-beta10-2021-12-09

GitHub releases:

• There's no way to view it all on one page and Cmd/Ctrl-F

• Releases are spread across 10, 20, 30, 40 + pages

  

  Above: webpack's releases

[Josh-Cena]

We do both. I do find value in GitHub releases (being able to share a particular version's changes; good for marketing) as well as the CHANGELOG (a centralized place to browse all versions). In addition, we now have this: https://docusaurus.io/changelog