Every project needs a changelog. And let's be honest, the work keep-a-changelog did to make this a more common practice is awesome. But there is something many seem to forget: Did you ever notice [version numbers] in release titles within a CHANGELOG.md? These brackets were supposed to be links. But in reference style, you need to complete the reference elsewhere. Let's look at an example (also in the wild):

## [0.18.3] - 2025-04-19

- Lost: reference to the version number 0.18.3 somewhere

This snippet, produces the following output:

[0.18.3] - 2025-04-19

• Lost: references to version numbers

However, if you scroll to the bottom of the keep-a-changelog example, you can see that the version numbers in brackets, have their link completed at the bottom. And rendered, it looks like this.

So how do we fix our changelog? By adding reference style links:

## [0.18.4] - 2025-04-19

- Found: references to version numbers

[0.18.4]: https://github.com/foresterre/cargo-msrv/compare/v0.18.3...v0.18.4

This produces the following output:

0.18.4 - 2025-04-19

• Found: references to version numbers

Don't like linking to the diff?

Not a problem. Use an alternative like a release page or something else you like. Or just leave the brackets out:

0.18.5 - 2025-04-19

• Also good: This version number has no link

Call to action

So next time you write a changelog, please keep these digital tumbleweeds out. Complete your links, fix your [brackets]!