search

vweevers / common-changelog

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

Guidelines when a PR results in more than one changelog entry #8

Open Blacksmoke16 opened 2 years ago

Blacksmoke16 commented 2 years ago

In most cases a PR results in one notable change within the changelog. However it might be worth adding some guidelines for when a single PR introduces multiple noteworthy changes. An example of this could be a 1.0.0 => 2.0.0 that happens within a single PR; which removes features, adds new features, and changes how previous features worked. Currently I can think of three ways to handle this:

  1. Add a single Changed change saying Refactor the code ... with a reference to the PR
  2. Add each noteworthy change with a reference to the same PR (possibly using a reference link like the version headings)
  3. Add a single Changed change, with sub bullets for the noteworthy parts
vweevers commented 2 years ago

I find it difficult to write guidelines for this because it depends on several factors (e.g. was everything planned out before the PR started or was the PR opened early in order to discuss open questions; was the PR squashed or do you have individual commits that can be referenced; how many changes are we talking about; are added features documented elsewhere; etc).

Option 1 can work if the referenced PR has a description (or short enough history) that explains the changes. The risk is that readers miss it. They might not follow the reference link if they assume the changelog summarizes everything for them.

Option 2 solves that (with a small cost of redundant information) and is my personal preference. Unless we're talking about a complete rewrite with many changes. There is a point where a changelog would be too long, too dry, too boring to read. In that case I'd prefer a separate upgrade guide, which also gives you a place to explain the motivation for refactoring, which can in turn motivate the reader to upgrade.

Option 3 is currently not allowed by Common Changelog, because too much information hurts the ability to quickly scan a changelog. More importantly, it muddles the categorization of changes.

Some general guidelines could be:

  1. Avoid the term "refactor" if it should not be interpreted as an insignificant, internal change
  2. If git history or pull requests do not sufficiently separate changes, then do this in the changelog
  3. If the resulting changelog would be too long (what is too long?) then ...
vweevers commented 2 years ago

possibly using a reference link like the version headings

I tend to avoid this so that content can be copied in full to e.g. a GitHub Release (though that is a limitation of tooling, really, so not a good argument on second thought).