Unclear Guiding Principle

[effemmeffe]

I'm trying to keep a changelog for my project, but I don't really understand that does it means the line "Versions and sections should be linkable" in the Guiding Principles from the website, care to explain? Or to point me to something to read?
TIA

[pineapplegiant]

This video has been pretty useful for me.

I think what they mean is that URLs will basically link to tags which compares the two versions. This is nice so users can see the diff of changes.

Taking a URL from their examples from the bottom of the emedded changelog.md on the website you get this:
https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0?diff=split. I think you're right though, they could probably explain that bullet more, but I think they just mean links that compare the code to the last release.

[olivierlacan]

Given the changelog example prominently displayed on the website:

# Changelog

...

## [Unreleased]

## [1.1.1] - 2023-03-05

### Added 

GitHub's markdown renderer automatically generates anchor links for each of the heading, allowing anyone to easily link to each specific section, which makes it much easier to find a specific version release when the Markdown is rendered:

If you copy the link shown above, it will always put this version release at the top of users' browser viewport:

https://github.com/olivierlacan/keep-a-changelog/blob/main/CHANGELOG.md#111---2023-03-05

That's because an anchor is created by the Markdown renderer surrounding the h2 HTML element:

That's what I mean by linkable.

This extends to change sections as well since most Markdown renderers worth their salt will generate unique anchors even if the section names are identical between different version releases:

So even if it's less clear, a link like this will go to the first listed "Fixed" section on the rendered changelog page:

https://github.com/olivierlacan/keep-a-changelog/blob/main/CHANGELOG.md#fixed