As mentioned in
UIU-626, I spent literally most of my working day yesterday on rolling release 2.13.0 of the Users app. Its changelog consists of 95 entries, going back a little over nine months to the previous release 2.12.0 of later November 2017.
Now part of the problem is of course that we let this module go three quarters of a year between releases – something that is all too easy to do now that we've become reliant on the crutch provided by the folioci NPM repository. But that really only exaggerated the size of the problem, which was the sheer archaeology involved in figuring out which Jira issues were involved. That includes:
- Reconciling the issues listed in the changelog with those tagged to the release in Jira.
- Version-tagging Jira issues that are mentioned in the changelog.
- Writing changelog entries for issues that are tagged to the version but not mentioned.
All of this might sound as though it ought to be straightforward, but it's not. Often changelog entries don't match their corresponding Jira-issue descriptions at all – and for good reasons. For example, the Jira issue reported a manifestation of a bug, and the changelog describes what actual fix was applied. In several cases, the title of the Jira issue seemed to bear no relation at all to what was done, and only reading through the linked PRs was I able to establish what happened.
One question would be: is this worth it? Does a comprehensive changelog really get us much? Who in fact sits down and reads the changelog? And if you add up all the time that it saves for all the people who do, does it come to as much time as it cost me to put it together? I suspect not.
So consider this: what if we simply do not maintain change-logs? Instead, part of the release process would be to auto-generate a simple change-log which is merely a list of Jira issues that were fixed as part of that release. We then have a single source of truth, and the need to reconcile multiple sources is eliminated.
For this to work, we would need much better Jira discipline from certain developers: in particular, every single issue that gets closed would need to be tagged to a release. (Perhaps Jira can be configured to require this?) It would also be helpful if part of the process of closing an issue was, when necessary, rewriting the issue summary to describe what was actually done, as opposed to the manifestation that led to the work happening.
Two more benefits if we took this approach:
- The generated change-logs could easily include links to the Jira issues, for those who want more detail – and, via those issues, to the PRs and commits that made the change.
- Almost all of the release-rolling process could be automated.
What does everyone think?