In this blog post I will give an overview of how I regard change logs, how and why they should be written and structured. Do note that this is base...
For further actions, you may consider blocking this person and/or reporting abuse
Hi, good post!
These are great good practices for developers, but how about end users? We partnered internally with the Product Marketing team and implemented a tool called Beamer (getbeamer.com), which is helping them a lot in the process of communicating new features, bug fixes, and other updates.
Well the audience of the Change Log I talk about aim primarily at developers or in some cases perhaps even super users. I will have a look at the link you provided - thank you very much.
Thanks <3
If you are using GitHub as your repository host, I would recommend authoring release notes rather than maintaining a change log. Autoprefixer has a pretty good releases page as an example.
The benefits of GitHub releases:
Hi Daniel,
That is good advice, my goal with the article was however not to promote or require any special tools or platforms. The change log accompanies the release and your consumer might not have online access.
Anyway I do use the GitHub release facility in conjunction with the change log file accompanying my software myself. The software is distributed via other channels, I just copy my entry from the change log file into the text field for the GitHub release (see example Perl distribution example).
This would work for a lot of software, like Perl distributions or Visual Studio Code extensions etc. where the change log is being made available for consumption by the toolchain or similar. Other distribution channels do seem to approach this differently where nuget for .NET seem to lean on linking to facilities like the one you mention.
You also need to highlight any breaking changes that come with a major release.
If you release a new major version (first number in semantic versioning), users wishing to upgrade will be viewing the change log to find out if there was a breaking change that affects them.
I generally split change logs into these headings:
Good suggestion, I wanted to mention this, but forgot to get around to it when attempting to avoid a discussion on version numbering and especially semantic versioning, so it is clearly missing from the blog post.
I have observed a lot of different versioning schemes so you cannot necessarily rely on semantic versioning, where this is implicit in the usage pattern. This does however underline the importance of emphasising breaking changes in your change log, no matter the versioning scheme used.
Thanks for the comment and feedback
Great read! I've implemented a few of these in my recommendation for an updated change log! Thanks.
Thank you Ross
If your change log is public available please let me know I would love to see it :-)
jonasbn
Today I fell over the following article: "Apply Changelog Best Practices to Development", which references (among other things) this "Keep a Changelog" tool, which might be of interest to you.
Have a nice day
jonasbn