Isn't a CHANGELOG about all changes not just important changes?

[olivierlacan]

Several interesting comments on Twitter from Caleb Thompson and Aaron Patterson.

Caleb Thompson: @olivierlacan That’s exactly a changelog. NEWS is a record of changes between releases, which is what you want. http://t.co/bneYwnliy3

Caleb Thompson: @olivierlacan NEWS is for important changes, not every change as a log of changes would be.

Caleb Thompson: @olivierlacan Here, have some more. https://t.co/BCggwhnJnr https://www.gnu.org/prep/standards/html_node/NEWS-File.html#NEWS-File https://www.gnu.org/prep/standards/html_node/Change-Logs.html

Aaron Patterson @mperham end user focused changes should be in NEWS.

I think the GNU standards are definitely something this project will have to take into account. I do have an initial dislike for the NEWS file idea because of its atrocious semantics. NEWS tells me much less about the purpose of this file than CHANGELOG does. And its focus is not obvious at all, which I believe should explain why there's so much confusion around the naming of end-user focused change logs.

It also wouldn't be the first time people from the GNU community commit semantic crimes. Another proof that — yes — naming does matter, a lot.

[calebhearth]

I do have an initial dislike for the NEWS file idea because of its atrocious semantics.

README.md really only has organic semantics as well. They're not always great, but generally speaking they are useful.

This is probably because GitHub decided that it should be so by giving them first-class treatment in repositories. This should happen with NEWS as well.

Another proof that — yes — naming does matter, a lot.

README -> This is a thing that you should read CHANGELOG -> Here is a log of all of the changes NEWS -> Here's some headlines

[calebhearth]

I'd love to see a standard built up around NEWS files. A project I maintain, Griddler, has recently started keeping pretty good notes in tags, which are the closes thing we have so far to a first-class version of NEWS.

The important parts of that are:

• Detailed explanations of things that are particularly interesting, or that will break backward compatibility. This also includes links to commits and/or pull requests, and can optionally include author information (though that can be gathered from the former).
• A list of minor but noteworthy changes that were hand-selected from git log --no-merges --reverse --pretty=format:* %s.. In the case of NEWS.md, this can and should have been things which were added along with the functional changes.

[calebhearth]

Finally, CHANGELOG isn't a useful file in the age of version control, where that information exists more properly in logs, which is why we've moved to NEWS-style files with various names.

[ixti]

IMO CHANGELOG should mention changes from high-level perspective (the one that GNU proposes to write down into NEWS). And thus NEWS becomes useless.

To explain my point. GNU's coding standard proposes to duplicate git log with CHANGELOG, and introduce less noizy version called NEWS (at least it seems so to me). I believe one should write good commit messages, those anyone who wants to see changes per file between versions will use git log, and CHANGELOG should mention new features, deprecations, fixes, security fixes and so on. In this case one can first look to changelog to get release that potentially was related to his bug and then see git log for detailed changes.

[olivierlacan]

@calebthompson In my mind the word News doesn't carry the meaning Change Log does. Yes, you have to qualify "Change Log" by saying that it's only meant for "notable changes" but that's not a huge leap whereas what qualifies as news-worthy seems a bit more nebulous to me.

I don't think what we envision (whatever the file name) should include links to pull requests or authors. That's a job well done by commit messages, especially those enhanced by GitHub's nice issue/PR auto-linking. The one release-specific link I think matters most is the compare view one I recently added to the CHANGELOG.md example.

[darkfeline]

I think there's a misunderstanding here between change logs and release notes (NEWS, RELEASE).

Change logs are indeed for storing all changes. I believe this dates back to when wonderful version controls like Git did not exist. In such a world, keeping a list of all changes is very useful, hence the existence of the change log. I refer to the GNU documentation on change logs, which clearly expresses this intent.

Release notes, on the other hand, are what Keep a Changlog is really trying to be. I refer to the GNU documentation on NEWS files and Wikipedia.

Now that we have good version control tools, I agree that it's a good idea to retire the ChangeLog file and agree on naming release notes as either NEWS or RELEASE (with some standard extension). I don't think trying to forcefully redefine "change log" is a good idea however.

[ghost]

I know that the intention of the keep-a-changelog are good and quite necessary, After reading a couple about this, and after almost 5 years using the CHANGELOG way, I think ends up being more like the old 'ChangeLog, pretty verbose and in big projects not pretty human readable and useful, for example: https://github.com/nodejs/node/blob/master/CHANGELOG.md, github release notes become more readable and closer to the old NEWS file https://github.com/nodejs/node/releases, also the oldNEWSfiles have been using for more than 25 years for projects such as Gimp/Gnome so is a example of success for long time using theNEWS` files, is not necessary reinvent the wheel.

After 6 years of this issue for me Isn't a CHANGELOG about all changes not just important changes? question still open, for example rust keep an CHANGELOG for sub-projects but in the main one it have RELASE file and seems to me that the RELEASE file is for important things and the CHANGELOG for more generic ones