Format/Contents of the CHANGELOG file?

Development
1

Hey,

I’d like to get some feedback on the format and content of the CHANGELOG.md file. Too much information? Not enough information? Is the information for you (as users) relevant? Is the format good or bad?

Cheers!

2 Likes
2

I like the current style of how you run the Changelog.
The information provided is concise and explains all the changes very well. I don’t think it is too verbose.

1 Like
3

Its not bad, at work I use http://keepachangelog.com which is a very nice human/machine readable format.

1 Like
4

I also think that the changelog it very good in its current form. Thanks for providing more than a simple list of commits!

5

I think the current format has a number of issues, even if it’s informative and good in many ways.

  • In a way it’s a big wall of text, which a lot of people won’t bother to read - I think a lot of users want to skim through a summary to quickly evaluate each change and whether it’s relevant or not to upgrade. Especially sysadmins and others who might be looking for a specific type of change.

  • The “Important changes” headings name the version they refer to, but the “Small changes” doesn’t, which makes it’ unclear what you’re reading about.

  • In general many of the points/items in the changelog are a bit too much text - having a summary would be good.

To get straight to the point, I’m hereby suggesting an (IMO) improved version of the changelog format, based on the current changelog for the 0.8.0 release (see comments below) -
please see: https://gist.github.com/anonymous/ef7bb9cc237ac18972c7369202bf611f

Some comments on it:

  • Yes, the details of small changes become a bit redundant when there’s a summary for them. Personally I’d skip the details section for small changes - people will simply go to the PR or issue and read more if they are interested.

  • If it doesn’t feel right with the credits in parentheses in the summary sections, they can be removed of course, although I think they’re nice to give credit right off the bat. They should list the most relevant people who worked on the change (obviously the programmer, but also anyone who contributed very much to the discussion or raised the issue and then helped out solving it).

  • The issue numbers in the summaries are taken from the most relevant issue, or the most relevant PR (if there’s no issue). When there are multiple issues and/or PRs for a change, these will be listed in the more elaborate info further down.

  • Not every change need a more elaborate description, if it’s a simple change then let it be mentioned in the summaries only. However, for sake of coherency and simplicity, perhaps it’s best to keep a 1:1 relation between the summary sections and details sections - when adding a change, do it in both places.

  • Please note that the Sec, Bug, Enh and Chg prefixes are grouped in order of importance - this makes it easier to skim through and identify what’s relevant to oneself, and obviously it’s good that the security and bug related things are at the top.

  • The above is just an example, perhaps I got the credits and the Sec/Bug/Enh/Chg prefixes wrong for the various items.

  • I also considered if there should be an Opt prefix (Optimization), for changes that are about improving performance and reliability. I think it might be a good idea, as quite a few of the changes were in fact for that purpose, and it can be relevant to people who are looking for that in particular, when deciding whether or not an upgrade is relevant.