The dos and don’ts of keeping a changelog
Is your documentation up to date? If you’ve been putting off updating your changelog, you’re not alone. A new initiative from Keep a Changelog encourages developers to be kind and stop dumping git logs into changelogs.
We’re all guilty of putting off boring and dull tasks. But incomplete documentation is more than just the last thing on your to-do list; it’s genuinely harming your project’s ability to attract and retain new users. Your changelog is more than just a way to keep track API versions; it’s a way to signal that this project has got its stuff together.
Last year’s open source survey from GitHub found that an astonishing 93% of developers noticed if there was incomplete or outdated documentation on a project. At the same time, 60% also reported that they rarely or never contribute to documentation. This mismatch causes serious problems.
Documentation is important. It tells newcomers how to use a project, how to contribute, and explains the standards of conduct in a community. These are not small, incidental things that can be ignored in favor of technical details.
GitHub’s survey found that that underrepresented groups value documentation that clearly explain a project’s processes. Additionally, users who didn’t grow up speaking English or read less-than-fluently prefer projects that have clear and accessible language.
That being said, there’s no real standard format for changelogs. Keep a Changelog intends to change that.
How to maintain a changelog
Making a readable changelog takes effort. Keep a Changelog wants to make it easier with a standardized convention for documentation. Although there is no set standards, it does have a few guiding principles.
- Changelogs are for people. They need to be readable and understandable by someone with a basic understanding of coding. There’s no point making things difficult; all you’re doing is driving away valuable community members.
- Every single version should have its own changelog entry. This keeps anything from falling in between the cracks.
- All changes of the same type should be grouped together for reading comprehension. If you throw a deprecated feature in the middle of a bunch of fixed ones, it’s likely to be missed.
- Provide links if possible! It saves time from googling and it makes sure everyone is on the right page for version changes.
- The newest and latest version should be at the top of the page. Think of your twitter feed.
- Document the date! People need to know when these updates were released.
- Do you use semantic versioning? Then tell people.
Keep a Changelog also suggests that the changes be differentiated in a few standard categories, like:
Addedfor new features.
Changedfor changes in existing functionality.
Deprecatedfor soon-to-be removed features.
Removedfor now removed features.
Fixedfor any bug fixes.
Securityin case of vulnerabilities.
What not to do
Just because there’s no standard format for changelogs doesn’t mean developers should create their changelogs willy-nilly. Here are a few simple pitfalls to jump over when working on your own documentation.
Commit log diffs. Commit log diffs are busy things, full of sounds and fury that signify nothing. They’re made up of unnecessary details like merge commits, commits with weird titles, documentation changes, and more. Stop padding your changelog with these things, okay?
Forgetting to update deprecations . If the latest version of a project has any breaking changes or isn’t backwards compatible, then please tell the users! This shouldn’t be a surprise to developers. At the bare minimum, list deprecations, removals, and any breaking changes in the changelog.
Date confusion. Okay, I fall for this a lot as an American living in Europe. People write the date differently across the world. Follow the ISO standard of YEAR-MONTH-DAY when you’re dating a version release and you should be fine.
Making a difference, one changelog at a time
Change (and changelogs) begins at home. By observing good documentation practices from the very beginning, developers can help the whole community without needing any herculean work to retroactively bring it all into compliance later.
Of course, the suggestions above are just that. Documentation for the open source community has evolved along these lines, but there’s nothing to say that everyone won’t make a sudden switch for a new style. But, by collectively collaborating to create a new standard, developers can help create a new changelog convention for everyone.
If you want to join the effort to clean up changelogs, you are welcome to send yours healthy criticism, discussion and suggestions for improvements here.