Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

olivierlacan opened this issue Jun 24, 2014 · 7 comments

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

olivierlacan opened this issue Jun 24, 2014 · 7 comments


Copy link

@olivierlacan olivierlacan commented Jun 24, 2014

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.

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.

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.

Copy link

@calebthompson calebthompson commented Jun 24, 2014

I do have an initial dislike for the NEWS file idea because of its atrocious semantics. 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

Copy link

@calebthompson calebthompson commented Jun 24, 2014

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, this can and should have been things which were added along with the functional changes.
Copy link

@calebthompson calebthompson commented Jun 24, 2014

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.

Copy link

@ixti ixti commented Aug 14, 2014

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.

Copy link
Owner Author

@olivierlacan olivierlacan commented Dec 13, 2014

@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 example.

olivierlacan added a commit that referenced this issue Feb 16, 2015
Yes, we know there's a GNU style guide for change logs:

It's not good enough. Or people simply don't know about it because
the GNU style guide has poor or inexistent examples and is far too
naive to be applied in many situations.
Copy link

@darkfeline darkfeline commented Sep 11, 2016

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.

olivierlacan pushed a commit that referenced this issue Jul 24, 2017
Copy link

@vxcamiloxv vxcamiloxv commented Nov 17, 2020

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:, github release notes become more readable and closer to the old NEWS file, also the old NEWSfiles 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants