search

vweevers / common-changelog

Write changelogs for humans. A style guide.
https://common-changelog.org
MIT License
126 stars 9 forks source link

Decide on sort order of releases #3

Closed vweevers closed 3 years ago

vweevers commented 3 years ago

Common Changelog currently contradicts itself. In the introduction it says:

A changelog is a file which contains a curated, chronologically ordered list of notable changes

Then later it says:

Releases must be sorted latest-first according to Semantic Versioning rules.

It's tricky to decide which order is best (and whether we should enforce it at all) because there are conflicting concerns. Consider these use cases:

  1. As a maintainer, having multiple release lines or hotfixes (maintained in git branches).
    • Side note: is there a "canonical" changelog?
  2. As a consumer, wanting to find the changes of the semver-last release. You're on 2.x and don't care about a 1.x release.
  3. As a consumer, upgrading from several versions back (e.g. from 1.x to 3.x) and wanting to read the changelog in semver-order
  4. As a maintainer, migrating from Keep a Changelog (which sorts chronologically) to Common Changelog

What use cases are there for wanting to see chronologically ordered releases?

ralphtheninja commented 3 years ago

I don't really see why you would want everything to be chronologically sorted. Say I'm on 1.x and not ready to upgrade to 2.x, but still want e.g. patches for bug fixes etc. Then it would be handy for me to look at the top and see updates to 1.x, but that use case is not the most common one, so if I'm on 1.x and want to see release notes for an update to 1.x I might as well have to scroll down to the 1.x-line and pick the latest there. So maybe sort chronologically per server major?

vweevers commented 3 years ago

So maybe sort chronologically per server major?

The same problem exists on "minor release lines" - when you release a hotfix for say 1.2.x and 1.3.x - though this is less common. We might as well sort all by semver, because typically that's effectively the same order as chronologically per server major.