6 Reasons to Maintain a Changelog in Your Codebase
It’s important to understand where you app came from
As a software developer, I love to code on cool new features or critical bugs. But at the same time, I used to avoid writing detailed documentation and maintaining a changelog or releases to keep track.
Now, after a few years, I’ve learned the importance of keeping good documentation or a changelog. After reading “Clean Architecture,” I gained a whole new perspective on code management. Documentation makes it easier for new developers to get up to speed, changelog helps all team members keep track of releases. And there are many more perks!
In this article, I would like to share a few points on why I think a changelog should be maintained for a codebase and how it can pay off in the long term.
Before going further, what exactly is a changelog?
A changelog is a log or record of all the changes made to a project, such as a website or software project, usually including such records as bug fixes, new features, etc. — Wikipedia
1. To Keep Team Members on the Same Page
When multiple people are working on a project, the chance that they’re aware of all the changes becomes slimmer. Project management tools (like JIRA) focus more on the tasks you’re working on or you will work on in the near future. The changelog actually represents the current state of your codebase. With each release, all team members are aware of exactly what was fixed or merged. It can also be seen as a timelapse for your code project.
2. Debugging Production Bugs
Production bugs are every developer’s nightmare. We try our best to avoid them but sometimes they just happen. It may not be often but it is often critical, so it’s essential to have a good debugging strategy. With a well-maintained changelog, you can check what was published in last release and drill down to the root cause.
It’s always good to have a systematic approach to solve things. This top-down approach can be a good start: “What was released recently? What are the PRs involved? Which PR is linked to the bug?”
3. Valuable Data for Project Insights
The well-maintained changelog is basically a history of your codebase. It’s a list of all the changes that have occurred in the project, with a timestamp. We can gain a lot of valuable insights from it and it can be used to keep track of a project’s productivity. We can get metrics, like the bugs-to-features ratio, to get an idea of the project's health. We can get analytics on our project activity over time, which can be used to create a future project roadmap or get an idea of what team should be focussing on.
For example, “Last month, we had ten feature releases and two bugs. The team really made amazing progress. We have room for more user features.” Or “In the last three months, we had twenty bugs and four features — we really need to focus on reducing the number of bugs.”
4. Not That Difficult to Maintain
It’s a lot easier to maintain a changelog than you think. If you don’t like to do it manually, there are options to automate it for every platform: Github, Bitbucket, or Gitlab. Other than open-sourced projects to create changelogs automatically, Github also has a marketplace with many good apps and actions which can automate its flow.
5. Keep Users in the Loop
This is mostly applicable to open-sourced projects but startups can also maintain a public changelog. It’s to keep your users aware of the team’s progress. It can be a huge boost to the team’s morale if users are excited about the team’s progress. Many companies like Github, Slack, etc maintain a public changelog. Links: Github Changelog, Slack Changelog.
6. Re-learning From the Past
This point is taken Tom McFarlin’s blog because it conveys the point beautifully:
The likelihood that this is the only project on which you’ll ever work is pretty low. And as you become more familiar with new projects, you tend to forget concepts in previous work.
When it comes time to revisit this past work, it will take you that time to re-familiarize yourself. Furthermore, if someone else comes on board between when you started and when you resume work, they have to play catch up by reading through the source code and whatever notes you may have left inline.
That’s no fun for them and that can just add to the amount of time it takes to complete a project.
Thanks for reading. I hope this helps. Please don’t hesitate to correct any mistakes in the comments or provide suggestions for future posts!
