In DeSmart, we always work on several projects at once. Every project’s codebase is developed by several programmers. We all know that writing documentation or a changelog is a tedious and time consuming task. That’s why we – as well as basically everybody else – tend to skip that part of the development process. After some time you have to get back to the project (or join another team) and need to know what’s actually going on. And it begins – you’re cursing the team and often your past self for not providing a decent documentation.
The same goes for the changelog: when was this feature added? Since which version is this accessible? When was it refactored? The client asks what’s new?
To know the answers to these questions you often have to dig through Git logs, not knowing exactly what you’re looking for. What a waste of time, right?
What if the changelog’s generation could be automated?
ReadmeGen is a tool (written in PHP) that allows you to generate the changelog automatically. It scans the Git log targeting specific commit messages and puts them (organized) in your changelog file. As a result, you get something like this:
Project name and description. (...) Changelog 1.9.0 (2014-12-30) Features - New parser implemented (v3). - OAuth can now be used to log in the user. Bugfixes - Fixed a bug causing the app's crash during heavy upload (#2456) 1.8.13 (...)
How does it work?
In order for ReadmeGen to fetch a commit message, it has to be prefixed with a specific keyword. For example, this commit message will be put in the “Features” section:
feature: New parser implemented (v3).
…while this one will not:
Added something somewhere.
ReadmeGen checks if a commit message starts with one of the defined keywords and puts the message (stripping out the prefix) into a specific group. This tool comes with a default config file which defines four groups of messages (features, bugfixes, documentation and refactoring). ReadmeGen is highly customizable so you can, for example, fully override the default config and define your own message groups.
Usage
You can install ReadmeGen using Packagist.
This tool is designed to be installed globally via Composer. That way you can use it in all of your projects without including it in the composer.json file every time. Once you have Composer installed, just run:
composer global require fojuth/readmegen:@stable
Protip: you can find detailed installation and usage instructions on ReadmeGen’s homepage. Once ReadmeGen is installed, you can run it inside your project’s root directory:
readmegen --from 1.12.0 --release 1.13.0
The script will scan the Git log starting from tag 1.12.0 up to HEAD, grab all the commit messages that start with a proper keyword, organize them, and put them inside your changelog (readme.md by default) naming the release 1.13.0. Simple as that.
Issue tracker links
ReadmeGen is also capable of linking issue IDs to an issue tracker of your choice. If you have a sequence of digits with a # sign in front of them (e.g. #2910), ReadmeGen will assume it’s an issue ID and will link it to the issue tracker defined in the config file. Useful when you want to take a glimpse at the ticket the feature / bugfix is related to.
Clients love it = you’ll love it
In the past, much darker times, our clients asked us to sum up what has changed since the last update. We used to dig through our commits / tickets / emails. Too often we missed something or duplicated stuff from previous releases.
Now, this problem is gone. The only thing you have to remember is to prefix the commit accordingly. When we make a new release, we run ReadmeGen, copy the output from the readme.md and send it to the client. He knows what’s going on and we can continue with our work. The time saved is beneficial for both sides.
Apart from that, the application’s development history is saved into a single file which helps future devs to grasp and understand the whole process. It also helps us to know what happened in the process and precisely when.
Try it out, give us feedback
Tell us what you think about ReadmeGen. What’s your opinion? Did it help you? Any ideas or issues encountered? Let us now in the comments or on the project’s GitHub page!
Drop us a line here, and let’s talk about how we can go about it.
