Empty Unreleased header makes it look like the latest version might be unreleased

[erikhuizinga]

If the unreleased section is empty, the unreleased header goes right above the latest release header. For example, the current CHANGELOG.md shows this.

Screenshot

This makes it seem as if version 1.1.0 is unreleased, even though that version has a date. The only thing indicating the separation between the Unreleased header and the latest version header is a thin line, rendered by the markdown renderer. If that ever changes, the distinction changes as well.

A possible solution:
Add a placeholder text in the Unreleased section, for example:

# Unreleased

_No unreleased changes_

# 1.1.0 - 2019-02-15

Another possible solution:

# Unreleased

# [Latest] 1.1.0 - 2019-02-15

I prefer the former, though, because the latter can still be interpreted as 'the latest release is unreleased'. A combination of both proposed solutions might also work, for explicitness. The changelog is for humans to read, after all, so ambiguity is best avoided.

---

Please consider clarifying the latest release by separating it well from the Unreleased header.

[olivierlacan]

Good note! I could swear I used to have a line in there in the past.

[Chofoteddy]

Another solution would be a "Released" section (that links to repo/releases).

Screenshot

[rdeago]

IMHO a "Released" section would be unnecessarily redundant. The same goes for the link to repo/releases: releases are already listed in the changelog, (hopefully) each one linking to the specific release page.

I think a "No unreleased changes" paragraph elegantly solves the problem of someone possibly mistaking the latest version for an unreleased version.

Tagging the latest version with "[Latest]", on the other hand, would mean moving the tag at every release. It is also redundant, since releases are listed in reverse order, so the first one you see is the latest by definition.

[malaire]

... releases are already listed in the changelog, (hopefully) each one linking to the specific release page

According to https://keepachangelog.com/ each release should link to comparison with previous version, not to specific release pages.

[rdeago]

According to https://keepachangelog.com/ each release should link to comparison with previous version, not to specific release pages.

I could not find that on https://keepachangelog.com/ but maybe it's just me, and the fact that it's now 7AM here. Anyway, I was referring to GitHub release pages. As for comparison with previous versions, isn't that the point of the changelog itself? Unless you're talking about the relevant section of commit history, which is also linked to in every GH release page IIRC.

[malaire]

I meant the example changelog there which shows how changelog should be formatted.

It uses links like v0.1.0...v0.2.0 for 0.2.0.

[holistic-developer]

I maybe misunderstanding your issue, but i think the right way would be to leave out the unreleased section at the commit that gets released, because at this point in time there is nothing that is unreleased.
Add it again after the first unreleased change.

[erikhuizinga]

@holistic-developer that is yet another approach that could work for various cases. In some other cases the unreleased section would work like a reminder that the changelog can be written while developing parts of a release.