Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Keep a Changelog

keepachangelog.com

Post reply on HN
Print view View original

31–40 of 47 posts

Re: Keep a Changelog

#31

Post by crististm »

teddyh wrote: post #27

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 compa…

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?

Re: Keep a Changelog

#32

Post by teddyh »

crististm wrote: post #31
teddyh wrote: post #27

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 compa…

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

Re: Keep a Changelog

#33

Post by orkoden »

JoshTriplett wrote: post #9

Projects that still insist on maintaining a changelog file in git end up constantly fighting git's conflict resolution, and they make rebase almost completely unusable. For an actual log of individual changes, that's what "git log" is for; any project that pre-dates git should "git mv ChangeLog ChangeLog.pre-git". And if your "git log" output isn't highly readable, write better commit messages and group changes into…

The last project I was working on only edited the changelog file when a release was cut. As we tagged each release with a version number, it was easy to get the commit messages since the last release with:

    lastTag = `git describe --abbrev=0 --tags`
    git log --oneline --no-merges #{lastTag}..HEAD | cut -c 9- | sort
Then you just need to edit that list down to the relevant details. This was part of a release script which also added things like increasing the version number, generating md5 hashes for the binaries, date etc.

If you have something like a changelog, it's important to keep the audience in mind. In this case the audience was mainly the internal test department and marketing. Testers also had access to the bug tracker of course and only used the changelog to get an overview. Marketing and support used the changelog as the basis for their communication with customers.

Re: Keep a Changelog

#34

Post by olivierlacan »

teddyh wrote: post #27

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 compa…

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.

Re: Keep a Changelog

#35

Post by FooBarWidget »

teddyh wrote: post #27

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 compa…

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.

Re: Keep a Changelog

#36

Post by teddyh »

FooBarWidget wrote: post #35
teddyh wrote: post #27

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 compa…

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; the…

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

Re: Keep a Changelog

#37

Post by FooBarWidget »

teddyh wrote: post #36
FooBarWidget wrote: post #35

Earlier quoted context omitted.

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; the…

> 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 aban…

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.

Re: Keep a Changelog

#38

Post by fafner »

FooBarWidget wrote: post #35
teddyh wrote: post #27

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 compa…

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; the…

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

Re: Keep a Changelog

#39

Post by teddyh »

olivierlacan wrote: post #34
teddyh wrote: post #27

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 compa…

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 r…

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.

Post reply on HN