Ask HN: What Makes a Good Changelog?

5 points by Xavdidtheshadow 3 years ago | 4 comments
When you have to update your project's dependencies, you (presumably) look at the changelogs for each package to see if you can safely update. This experience varies wildly based on how well changes are tracked and documented (if at all). I'm looking to suss out what separates a great changelog from a mediocre one.

  - What bits of a changelog are most helpful / important? 
  - What's not helpful, but usually included?
  - How should the document balance skimmability / comprehensiveness / readability?
  - What projects have the most helpful changelogs?

Thank you!
  • macshome 3 years ago
    Overall I like the format and advice from https://keepachangelog.com/

    We’ve adopted it at work and it’s nice to have a consistent format that is relatively noise free.

    • Xavdidtheshadow 3 years ago
      I like some of their ideas for sure. I think it's a good starting point.
    • trinovantes 3 years ago
      Honestly, the only things I care about are breaking changes and migration steps

      Everything else is just noise

      • Xavdidtheshadow 3 years ago
        Sure, makes sense! It's a tough balance to strike, to be both informative enough to cover all the cases and slim enough to show only the breaking changes.