vweevers / common-changelog

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

Decide where to put notes #1

Closed vweevers closed 3 years ago

vweevers commented 3 years ago

As described in 3.8. Add historical notes:

Occasionally releases need a note to clarify status or inconsistencies that could cause confusion. For example when a release was yanked, the format of git tags changed, or when an external change negated statements made in the changelog.

In the Level org we've used the following format (links omitted):

**Historical Note** This release was not published to npm due to security issues (#123).

To improve readability I tweaked it in Common Changelog to:

**Historical note**

This release was not published to npm due to security issues (#123).

But I'd like to make it more semantic. How about using the same heading format as a group of changes?

### Notes

This release was not published to npm due to security issues (#123).

Altogether that would look like:

## [2.1.0] - 2021-05-09

### Added

- Support CentOS (`53bd922`)
- Add `write()` method (`15d5a9e`)
- Document the `read()` method (`75ee538`)

### Notes

This release was not published to npm due to security issues (#123).
vweevers commented 3 years ago

External feedback that I got:

So, change of plan. If a note is important, it should be at the top of the changelog entry (which means a link to an upgrade guide is a note too). If not important, leave it out. To enforce this, there can only be one note.

Use cases (these happen to be mutually exclusive):

  1. Link to upgrade guide (see 2.2. Release)
  2. Yanked release (6.3. What about yanked releases?)
  3. Promoting a prerelease to a release, without changes (3.7. Promoting a prerelease)

Example:

## [2.1.0] - 2021-05-09

_This release was not published to npm due to security issues (#123)._

### Added

- Support CentOS (`53bd922`)
- Add `write()` method (`15d5a9e`)
- Document the `read()` method (`75ee538`)