Changelog format

[dbanty]

Now that we're on v3 of the changelog format (implemented in #969), I figure it's worth documenting the history and design decisions—as well as having a place to discuss further future updates with historical context.

v1

Initially, changelogs always looked like this:

## <version>

### Breaking Changes

- change
- change

### Features

...

v2

To support more rich descriptions with changesets, all changes were documented with a fourth level header (####) instead of a bullet. This is mainly because associating rich content visually with bullets in Markdown is very difficult. Dates were also added to version headers at some point.

## <version> (<date>)

### Breaking Changes

#### change

#### complex change

with details

...

v2.1

We added the ability to detect existing changelogs that used a first-level header (#) for each version instead of a second-level header. If detected, each header that's normally produced would be promoted. So sections become second-level, and changes become third-level.

v3

Driven by #930, we moved to a sort of hybrid between v1 and v2. Having standalone headers with no content between them can be hard to read. So for simple changes that would have been a lonely header line, they now appear as bullets at the top of the section (they cannot be left in the previous order, or the bullets could appear below another change's header). More complex changes (changesets with content below the header) are still rendered in the v2 form. Example below intentionally rendered by GitHub to see the comparison.

v2-style section

A complex change

with details

A change

Another change

v3-style section

• A change
• Another change

A complex change

with details