Posted over 2 years ago. Visible to the public. Repeats. Linked content.

How to write a good changelog

We want to keep a changelog for all gems we maintain. There are some good practices for writing a changelog that adds value, please stick to these.

  • Add a notice to the README's contribute section about the changelog
  • For every release update the changelog
  • Note the date format yyyy-mm-tt

What is a changelog?

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

Why keep a changelog?

To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

Who needs a changelog?

People do. Whether consumers or developers, the end users of software are human beings who care about what's in the software. When the software changes, people want to know why and how.


All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning]( ## Unreleased - Added `Foo#foo` method. ## 1.0.0 - 2017-06-20 ### Breaking changes - Renamed `Foo` to `Bar` - Removed `Baz#method`. Please use `Qax#method` instead. ### Compatible changes - Added new `Bam#foo` method. ## 0.9.0 - 2017-05-20 ### Compatible changes - Improved performance of `Bam`.

makandra has been working exclusively with Ruby on Rails since 2007. Our laser focus on a single technology has made us a leader in this space.

Owner of this card:

Emanuel De
Last edit:
over 2 years ago
by Henning Koch
About this deck:
We are makandra and do test-driven, agile Ruby on Rails software development.
License for source code
Posted by Emanuel De to makandra dev
This website uses short-lived cookies to improve usability.
Accept or learn more