keepachangelog.com of your stuff?

admindev, VCS0 Comment
3 min. reading

I am not intend to tell you that you should keep a change log of any piece of software that you ever develop. This is as obvious as the fact that sun shines and fire burns. If you don’t understand this or disagree then you’re certainly at the wrong address.

However, with this article I am going to tell you about a specific way of keeping history of changes to your software. The one that keepachangelog.com suggests. The one that I immediately fell in love with.

There are many ways, methods, formats and structures for keeping history and changes of your software (or even hardware). Of course. Starting with Git.

What makes keepachangelog.com that unique (in my opinion) is:

  • It uses Markdown so:
    • Files are easy to read even if you read them in console or text editor
    • It renders a HTML page with clickable links, if you render .md file in any way
  • It suggests / supports Semantic Versioning which I personally adore
  • Each entry is split into “Added”, “Changed” and “Removed” sections

Since it uses Markdown’s double square brackets linking feature key information (changes) is not cluttered with links. And you have all links, to each versions mentioned above, nicely listed in the bottom of a file.

Here is some example of a keepachangelog.com file:

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Nightly]

## [1.0.0] - 2017-06-20
### Added
- New visual identity.
- Version navigation.
- Simplified and Traditional Chinese translations.

### Changed
- Fix typos in Brazilian Portuguese translation.
- Fix typos in Turkish translation.
- Fix typos in Czech translation.
- Fix typos in Swedish translation.
- Improve phrasing in French translation.
- Fix phrasing and spelling in German translation.

### Removed
- Support for v1 as previously mentioned.

## [0.3.0] - 2015-12-03
### Added
- Russian translation.
- Brazilian translation.
- Spanish translation.

## [0.2.0] - 2015-10-06
### Changed
- Remove exclusionary mentions of "open source" since this project can benefit both "open" and "closed" source projects equally.

[Nightly]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0
[0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0

As you probably noticed — this is a simplified version of a text from keepachangelog.com homepage.

Leave a Reply