Search code examples
versioningchangelog

Should changelogs for stable versions include changes from preview versions?


I am maintaining a library that uses semantic versioning. The current stable release is 1.7.0, and I'm about to release version 2.0.0. In preparation for this fairly major upgrade, I've been uploading "release candidates" (2.0.0-rc1, 2.0.0-rc2, etc.). The changelog for each RC release includes all changes since the previous RC/stable release. My question is, what should I include in the changelog for the final v2.0.0: everything since 1.7.0 or just the one or two minor things that changed since the last preview version?

I suppose I could just not include the RCs in the changelog, but that doesn't really fit the conventional changelog wisdom of including every publicly released version. This library doesn't have very frequent updates either, so it's not like including preview versions would generate a lot of noise in the changelog (which I suspect is part of the reason why big projects like Babel or ESLint don't include every preview release in their changelogs). Anyway, I'm curious to know what other project maintainers recommend. Thanks in advance!


Solution

  • Simple rules (according to doc and nature):

    1. Every released to public version must appear in changelog
    2. Records for each version have to include notable changes since the previous version of product in changelog