At the MailOnline we have not been doing microservices exactly but something definitely far from big, monolithic applications. This resulted in quite a few applications across the board. Many written in clojure or in node.js, javascript for the browser, or some other language. We developers take care of releasing our software which is perhaps the right way to go most of the times, using some CI tool and always trying to push for continuous delivery. Nevertheless the time had come when we were asked to provide some human readable information about the versions of the software we release. The request come from multiple sources: devs, devops and technical management all wanted this info. For a short time we could repel the requests by pointing people to our CI tool and/or gitlogs either in the command line or on github which we use to host almost all our projects -- rest is on bitbucket, just to make things even harder to track. On the top of that we use multiple issue tracking systems, yeah I know, don't ask: historical reasons. As these issues have very valuable information on what we are working on they should be referenced in these changelogs too.
When we realised that we can't really escape the changelog, release note request and to track things would actually help ourselves too we had practically to ways to go: either write these changelogs manually or write some code to generate them for us. Luckily almost from the beginning we were fairly good writing commit messages -- I read that some people actually use git hooks to validate commit messages and enforce certain rules: we are not that good but everybody in the group writes a meaningful one liner at least, referencing github or JIRA issues using tags like [wip] or [refactor]. That is fairly good base to build on.
On an other note a long annoyance of mine the release creation on github: why, oh why can't you automatically generate some changelog on github based on your commit messages? I am sure that would not work for everybody who wants to use the release facility on github but it should do it for many projects. So first round: let's do a bit of googling if the tool is already out there. Well... kinda... gitchangelog looks like exactly what we need. But looking at its sample config file: not that sure anymore. So I basically figured writing something with a similar set of features with simpler config, less code and easy to use for any project but even easier for clojure projects would be fun.
Hence happened gargamel which can be used as a leiningen plugin or with its CLI interface. It accepts any git refs to generate a changelog in between or can generate release notes between the two latest occurrence of some tags with a specific format (for example v\d\.\d\.\d). It uses mustache templates to generate practically any output format (tested with html and markdown) and with simple configuration based on regexes it generates custom sections and munges certain objects (like creating links to github/jira issues from issue references) in the commit messages. On the top of that it is able to create changelogs of project dependencies in projects where those dependencies are managed in a bower.json file.
So now we are able to plugin in change log and release note generation into our release process. We have two types of release note generation jobs on our CI tool: manual one where you can provide from and to git refs: this is used to generate changelog for release candidates and publish them in the appropriate chatrooms (we use slack heavily) for affected people to review. And we have an automated release note generation step which runs right after our production release. Integrating gargamel with CI and slack is the real win in this story. On the top of that on those open source projects I am involved in I can use gargamel now to create markdown changelogs for github releases. for example gargamel's own release notes.