Read more

How to write a good changelog

Emanuel
July 31, 2018Software engineer at makandra GmbH

We want to keep a changelog for all gems we maintain. There are some good practices Show archive.org snapshot 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?

Illustration web development

Do you need DevOps-experts?

Your development team has a full backlog? No time for infrastructure architecture? Our DevOps team is ready to support you!

  • We build reliable cloud solutions with Infrastructure as code
  • We are experts in security, Linux and databases
  • We support your dev team to perform
Read more Show archive.org snapshot

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.


Example

All notable changes to this project will be documented in this file.

This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).


## 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`.
Posted by Emanuel to makandra dev (2018-07-31 08:57)