Every time I upgrade my project’s dependencies using npm-upgrade and it cannot find a change log I create an issue titled “Add changelog”. Most of them were ignored, sometimes maintainers answer something that means “fuck off”, very rarely they listen.

A good change log answers these questions for the project’s user:

What’s the new value for my project in the new version?

What are the breaking changes?

How can I migrate my codebase to the new version?

Were my issues fixed?

A change log is a tool that helps you decide to upgrade or not and to evaluate the benefits and the cost of the upgrade.

A good change log is:

Written for humans, not computers.

Understandable by users, not just contributors.

Not a Git commit log.

Written by a project maintainer — don’t ask for a pull request.

You should read this awesome guide and add a change log to your open source project today.