Heathen Engineering

Reading a CHANGELOG and Semantic Versioning

Introduction #

A version number is a promise about what changed. Semantic versioning (semver) is the convention that makes that promise readable at a glance, without opening a single file, and a CHANGELOG is where the promise gets spelled out in detail. Between the two, you should be able to answer “is it safe to update” before you’ve updated anything.

Best Practices #

  • Read the changelog before updating, not after something breaks. A five-minute read is cheaper than debugging a regression you could have seen coming.
  • Pin to a major version, not “latest.” A dependency on ^2.0.0 (or the engine-package-manager equivalent) accepts fixes and features but not breaking changes you haven’t reviewed yet.
  • Write your own changelogs for the reader, not for yourself. “Fixed a bug” tells a future consumer nothing. “Fixed: TagContainer.Matches() returned false for exact-match queries against hierarchical tags” tells them whether it affects them.

Semantic versioning: MAJOR.MINOR.PATCH #

A semver version number has three parts, and each one is a specific promise:

  • MAJOR (the first number): breaking changes. Something that worked against the old version may not compile or behave the same way against this one. Bumping this is the only honest way to ship a breaking change.
  • MINOR (the second number): new functionality, backward compatible. Existing code keeps working; there’s just more available now.
  • PATCH (the third number): backward-compatible bug fixes only. No new API surface, no behaviour change beyond “the bug that was there is now fixed.”

So 2.3.1 to 2.4.0 should be safe to take without reading anything (new features, nothing removed or changed underneath you). 2.4.0 to 3.0.0 is exactly the version bump that means “read the changelog first,” because something you depend on may have changed shape.

Reading a changelog #

A well-kept changelog groups entries by kind, typically Added, Changed, Fixed, and Removed, newest version first. When you’re deciding whether to update:

  • Check Removed and Changed first. That’s where breaking impact to your own code will show up.
  • Check Fixed for anything matching a bug you’ve already been working around. You may be able to delete your own workaround.
  • Added is the safest section, new capability rarely breaks anything already relying on the old surface.

How Heathen’s own repos tag releases #

Every Heathen Foundation and Toolkit repo on Codeberg follows semver in its release tags. When a KB article or product page references “the current version” of something, it’s this same tag it’s pointing at, not a separate internal numbering scheme. If you’re integrating a Foundation directly (rather than through a package manager that resolves versions for you), checking the repo’s release tags and their changelog entries before pinning a commit or tag is the same discipline as checking any other dependency’s changelog.

Rate This Article!

Contents