This post describes how I use (and write) a changelog, which types of entries it has and which categories.

Here is an overview of all headline types, for quick copy & paste:

## :boom: Breaking Changes
## :gift: New Features
## :sparkles: Improvements
## :bug: Bug Fixes
## :wave: Deprecations
## :memo: Documentation
## :hammer_and_wrench: Internal

## Commits

If you are using a release notes generator, you should use these prefixes in your changelog entries:

If you are using the release notes generator, use these prefixes:

  • (bc)
  • (feature)
  • (improvement)
  • (bug)
  • (deprecation)
  • (docs)
  • (internal)

Overview over all types of entries:

💥 Breaking Changes

Changes that break previously working code. Implies major version bump!

🎁 New Features

New features added, that add new functionality to the library. Implies at least minor version bump!

✨ Improvements

Things that work better or in more cases than before.

🐛 Bugfixes

Thinks that should have worked before (but didn't), but do work now.

👋 Deprecations

Lists all added deprecations.

📝 Documentation

Changes in the documentation.

🛠️ Internal

Internal changes / refactorings that should have no functional impact on the end user.


SemVer Numbering Strategy

The rules are as follows:

Version above 1.0

  • If anything is in the "breaking changes" column: release (major+1) . 0 . 0
  • else if anything is in the "new features" column: release major . (minor+1) . 0
  • else: release major . minor . (patch+1)

Version below 1.0

Do whatever you want. And release 1.0.0 soon, thx.


Photo credit: emarts emarts