Apply Changelog Best Practices to Development

Why does any project need a changelog? The primary reason for a changelog is to convey noteworthy changes. In essence it's a form of communication to those who view the project to get insight of when something has changed, been added, removed, been deprecated, fixed or is important information relating to security. These changes are written in a less technical manner, allowing for people of most experience levels to benefit from a changelog being present. It is an easy location to find relevant information of value for developers and consumers.

Without a changelog, developers need to look through source code commit history with special tools to do the searches, look through various documentation or look through different versions of the source code. The changelog is placed wherever it will be most relevant and convenient, based on the project. We'll cover some strategies for placement shortly, but first let's discuss the basics of a changelog.

Many mainstream projects have their own variation of a changelog, each picking a standard the project owners preferred and then maintaining that design as they continue to update it. I would like to recommend the standard to be used is from keepachangelog.com. The changelog will be stored in a markdown file for ease of writing, and elegance for viewing.

Here, the changelog starts out with the title Changelog and a note stating what standard the changelog adheres to. Next is a section labeled Unreleased for current changes that are in the controller branch of the source code but not published as an official next version release. Then, the major sections are the version numbers followed with the date of the version release: [1.2.3] - YEAR-MO-DY. This format allows for easy search and tooling around the changelog.

Within each version section, or the unreleased section, you provide subsections labeled Added, Changed, Deprecated, Removed, Fixed or Security. And within those sections you write a bullet list of noteworthy things that apply to the action/subject of the section. It is also a very considerate to give credit here to contributors who did the work for that specific change. A section may look as follows (excerpt from keepachangelog.com):

## [1.0.0] - 2017-06-20
### Added
- New visual identity by @tylerfortune8.
- Version navigation.
- Links to latest released version in previous versions.
- "Why keep a changelog?" section.

Here the first line after the Added subtitle gives credit to the username tylerfortune8. Giving credit to contributors encourages new contributors to be more involved as they will feel like their work has been acknowledged. The example above is about the website itself and so the list of items is just plain English descriptions.

If you're writing a software library, then the descriptions will reference code and so they may not be as relevant to non-developers. However, this is fine. The purpose of the changelog is relevant to those who use the project so software libraries will be written for the software developers. Here's an example:

## [0.3.4] - 2018-08-08
### Added
- This `CHANGELOG.md` file.
- Method `RString.codepoints`.
- `CodepointIterator` which uses direct ruby calls to get character value
  from bytes as determeined by the strings own `Encoding` and produces
  them one at a time.

Here files, methods and code objects are using inline syntax highlighted by way of the backtick character. Code blocks may be entered here as well, but I would highly discourage it because we want to keep the bullet points brief and only related to the facts. A better place would be to put them in official documentation, commit logs and if necessary as a code comment (although code comments are a divisive subject within the programming community).

There are all kinds of projects in the industry and the size and scope of what's being done can vary greatly. This leads to potentially massive changelogs if a large project stored everything centrally. Because of this you may need to choose an alternative strategy for logging project changes rather than keeping them all in one file in the root directory of your project.

For small projects such as libraries, keeping a file named CHANGELOG.md in the root directory of the project is a perfect place to store all noteworthy changes. This may even be a viable strategy for large projects as the Rust language keeps a changelog called RELEASES.md. They provide developers and others much more detail on the changes per version because they create a blogpost/newsletter of each changelog per version released, and place it on their website's blog while also notifying people via email.

Sometimes the changelog details for a project are vast and keeping details in a single file doesn't make sense. For these cases, dividing changelogs into Major.Minor version release may make sense. The Ruby programming language keeps changelogs in their documentation folder. The Ruby changelog files themselves aren't organized in sections but rather are simply ordered by chronological changes. Ruby provides a more human readable format of changes in their NEWS files per minor version release. The news files organize details of changes alphabetically and references the relevant bug or feature number that's in their bug tracker if you want more details. This is a very decent solution for clearly communicating to others what changes have occurred.

Rails follows yet another different strategy for changelog design and management. A good principle for large projects is to modularize it into many sections, modules or components. In these cases, you can create a changelog per component in the root folder of each of those particular components' directories.

At first glance, though, it seems the Rails team chooses only to display changes since the last version in any one CHANGELOG.md file. The files don't provide sections, just a bullet list of changes. If this was all that they do, then it would be more difficult to search through the changelog as you'd need to be familiar with git to checkout different versions of the changelog. But thankfully that's not all the Rails team does for the changelog. Instead, they publish links to all changelogs on their blog under releases and provide elegant release notes on the guides section of their website near the bottom of the page following a Major.Minor Semantic Versioning release system.

Personally I'd like changelogs, even when divided amongst sub-components, not to have any past details erased. Let the changelog get to be very long with the most recent changes at the top. Changelogs are like the birds eye view of a map for where you've been and where you are. Not showing the past changes in the current log files adds a bit of obscurity and leads a developer to have to dig for older information.

Each project has their own design considerations to take into account. Not all projects are written in our native language so the format and focus of how changes are presented will vary from project to project.

What it comes down to is communication. Changelogs are all about communication. They fit into a nice niche that most other projects structures don't quite cover, giving clarity to the present and past, while acknowledging and crediting contributors, to create a tight community of software developers. Finding whatever means to communicate with others will help your project to thrive and work with that. If a changelog will do that for you, by all means use one. And for elegance, clarity, and future tooling, following a standard for a changelog such as the example from keepachangelog.com, will be rewarding both to yourself and to others.

• Read more about Ruby string encoding

• See how to measure performance metrics in Rails

• How CloudBees CodeShip supports a Jenkins X install