Comment by teddyh | Hacker News Reader

Comment by teddyh | Hacker News Reader

The author seems not overly familiar with the history and conventions of releasing software.

> Is there a standard change log format?

> Sadly, no. But I want to change that.

There is a standard change log format: https://www.gnu.org/prep/standards/html_node/Style-of-Change...

Most GNU tools (and many others) use this format.

The Debian changelog format which most people have seen is based on that format, and is compatible with it.

> What’s the point of a change log?

> To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.

Oooh, they mean a NEWS file. Standardized like so: https://www.gnu.org/prep/standards/html_node/NEWS-File.html

> What should the change log file be named?

> Well, if you can’t tell from the example above, CHANGELOG.md is the best convention so far.

> Some projects also use HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

> It’s a mess. All these names only makes it harder for people to find it.

Please use standard names. Details here: http://en.tldp.org/HOWTO/Software-Release-Practice-HOWTO/dis...

The GNU standard is good and all, but I've found that it's horribly out of date.

- The name "NEWS" is not what users expect. I used to have a NEWS file which documents major changes in a high-level way, per the GNU standards. But I kept getting requests from users to "keep a changelog", and I kept getting questions from users about where the changelog is. Apparently most users never bother to check the NEWS file; they don't even associate the filename "NEWS" with what they're looking for. 95% of the users associate that concept with the word "changelog". "Changelog" is the new "NEWS". After several years, I gave up the resistance and renamed by "NEWS" to "Changelog".

- The actual Changelog format, per the GNU standards, is useless in my opinion now that version control systems have gotten so good. In my opinion, the git history is exactly what the GNU changelog tried to be, with the added benefit that the git history is much easier to browse, query and manipulate.

> The name "NEWS" is not what users expect.

This, I suspect, depends on your user base. Apparently your users expect the name "changelog". (Do they all use that exact term? Could this usage be traced to a single source, common among your users?)

> The actual Changelog format, per the GNU standards, is useless in my opinion now that version control systems have gotten so good.

Indeed, I believe even GNU Emacs has abandoned (or is about to abandon) it, now that they have switched to git.

Yes my users all use the term "changelog". And outside of traditional GNU projects, I've never seen anybody talk about "the NEWS file". All I've seen is people mentioning "the changelog", by which they mean that which the GNU NEWS file is meant for.

You can write the commit messages in ChangeLog format. The format is independent of how you store it! You can then create ChangeLog files from the history for source tarballs. In fact many GNU projects seem to do that now.

Other projects (GNU Emacs) still continue to use ChangeLog files because it is easier to correct ChangeLog entries than editing the commit history (which in git is destructive).

I am. Based on the current status of change logs in many open source projects ((absence, poor quality, irregular updates), I believe these conventions can be improved upon and clarified. At the very least they can be explained better than a two line text file with not a single example.

The GNU conventions for change logs and news files are not exactly self-explanatory (semantics matter), which probably explains how rarely they have been followed to the letter. I have no data to back this up, but I doubt people who use and depend on open source software would discard this claim.

Now it's interesting to see this initiative mocked as a "not invented here syndrome" (Moru's comment). I did not define these guidelines, I merely gathered them from existing open source projects which were exceptionally good at communicating changes. The poor examples and the frustration that fueled this project came from projects that did the opposite:

- inconsistent (file naming, change categories, etc.)

- dumping git diffs which provides absolutely no value to end-users (OSS software users who need to regularly update their dependencies)

- littered with references to irrelevant issue trackers (which did not provide clarifications regarding the changes)

- poorly written with the wrong audience in mind (fellow project collaborators who have context vs. external users who don't)

- not given any dates or given confusing regionally-flavored dates

- and the crux of my frustration: not singling out and emphasizing API breaking changes and deprecations

Anyway, please don't dismiss this project because a convention exist in one community. This convention is not being followed for now and I would really appreciate your help in improving the status quo: https://github.com/olivierlacan/keep-a-changelog/issues

Thanks.

Your project to make more projects adhere to standardized naming conventions and follow more rigorous documentation and release practices is laudable, and I support it wholeheartedly.

Your project to create a standard format and file name for what you want is unnecessary, since these exist already. Furthermore, you seem aware of this, and seem to want to change the existing standards to your history-naïve preference. You don’t even go to the projects which are the keepers of said standards, but instead set yourself up as a competing standards body. This does not endear you to people such as myself, who are on the whole happy with the current system, and see no benefits to your proposed changes.

Relevant XKCD: http://xkcd.com/927/

I have considered lately the equivalent of the "engineer's notebook" but I am not aware of such files in most notable software projects. It is supposed to record and communicate project challenges, dead-ends, attempts etc. to other contributors (probably like HISTORY?)

Does it make any sense to do that in a project?

The file most likely to contain such information would probably be the HACKING file, which I’ve seen many projects use to contain an introduction for developers of the software itself (as opposed to building instructions or the user’s manual).

not invented here-syndrome

Reply on news.ycombinator.com