He says not to use your repository commit messages as the source for your changelog text.
That's exactly what I do use.
I started doing this after reading "The Pragmatic Programmer" where it's argued that the DRY principle should apply to everything including documentation.
It starts with the bug tracker. So when entering something in that I'll also add the text that I want to appear in the changelog for the user to see (these lines will have a // at the start).
When a bug/feature is completed a commit is made and the text in the bug tracker is the commit comment.
If the commit comment has a line starting with a // then that line will have another line inserted above it //Bug fix: or // Feature:
Finally on building the distributable the changelog is constructed entirely from the lines in the commit messages that start with //
That's also what I do. When releasing a new version, I run a script/gradle task/... that:
- compiles all commit messages since previous version
- filters unwanted messages (according to special tags)
- groups them by category (fixes, enhancements, ...)
- opens an editor so that a human can prettify the changes
- appends the end result to changelog
- updates version files
- commit changes / git tag / etc
EDIT: formatting
BTW, I always have to set up those tasks myself. I'm surprised some kind of standard tool does not exist. I guess everybody has their own preferences and no standard really emerged...
There are probably a lot of tools that do this. The conventional-changelog[1] is one project, and it links out many others. AngularJS is a good example of a project that's been using that style for quite some time. I ended up using that as inspiration for my own tool (similar to yours) because as you mention, a lot of the pieces can be idiosyncratic to the project, and it turned out to be a relatively straight forward affair anyways. But if I were starting an open-source (node) project today, I'd probably just use the standard-version tools and forget about it.
I like your idea of opening it in an editor to prettify it up. It seems to go at least part way to integration Help Documentation in the process which is something I'd like to achieve
I started doing this after reading "The Pragmatic Programmer" where it's argued that the DRY principle should apply to everything including documentation.
It starts with the bug tracker. So when entering something in that I'll also add the text that I want to appear in the changelog for the user to see (these lines will have a // at the start).
When a bug/feature is completed a commit is made and the text in the bug tracker is the commit comment. If the commit comment has a line starting with a // then that line will have another line inserted above it //Bug fix: or // Feature:
Finally on building the distributable the changelog is constructed entirely from the lines in the commit messages that start with //