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

Closed
olivierlacan opened this Issue Jun 24, 2014 · 6 comments

Comments

Projects
None yet
4 participants
@olivierlacan
Owner

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

@calebthompson

This comment has been minimized.

calebthompson commented Jun 24, 2014

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

@calebthompson

This comment has been minimized.

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

This comment has been minimized.

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.

@ixti

This comment has been minimized.

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.

@olivierlacan

This comment has been minimized.

Owner

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 CHANGELOG.md example.

olivierlacan added a commit that referenced this issue Feb 16, 2015

Clarify point about lacking change log standard.
Yes, we know there's a GNU style guide for change logs:
#2

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

This comment has been minimized.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment