Keep a Changelog • Hacker News Board

Re: Keep a Changelog

#41

Post by teddyh » Mon, Feb 16, 2015, 1:39 PM UTC

leni536 wrote: post #21

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…

I think neither a CHANGELOG or a NEWS file has a place in a git repo. Every file in every commit should be meaningful for the given commit. These are obviously usually source files or even documentation of the current behavior of the software. The problem with CHANGELOG and NEWS files that they are not meaningful to every single commit only for commits that are tagged as releases. I don't know what would be a good pr…

The ChangeLog file can certainly be cut, but the NEWS file? The NEWS file is only changed when a new release is made. Otherwise, the file is unchanged. I see no reason it should not be in the repository.

Re: Keep a Changelog

#42

Post by teddyh » Mon, Feb 16, 2015, 1:46 PM UTC

olivierlacan wrote: post #40

Before you run to educate me about GNU's change log style guide, please go read this: https://github.com/olivierlacan/keep-a-changelog/commit/3039... Thank you :-)

> […] or the two-paragram GNU NEWS file "guideline". The GNU style guide is a nice start but it is incredibly naive. There's nothing wrong with being naive but when people need guidance, it's rarely very helpful. Especially when there are many situations and edge cases to deal with.

Your project could easily transition to become a project to document, codify, and standardize existing NEWS file practices and conventions and also submit these as a patch to the GNU coding standards. This would be an effort I could support.

Re: Keep a Changelog

#43

Post by qznc » Mon, Feb 16, 2015, 1:48 PM UTC

The best and most extensive changelog I ever saw is D's: http://dlang.org/changelog.html

It documents and explains (with examples!) everything normal D programmer needs to know.

Re: Keep a Changelog

#44

Post by fbe » Mon, Feb 16, 2015, 3:48 PM UTC

teddyh wrote: post #39

olivierlacan wrote: post #34

Earlier quoted context omitted.

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…

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

Re: Keep a Changelog

#45

Post by [deleted] » Mon, Feb 16, 2015, 5:18 PM UTC

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…

[deleted]

Re: Keep a Changelog

#46

Post by shared4you » Mon, Feb 16, 2015, 11:05 PM UTC

hamstergene wrote: post #29

Why use so many levels of markdown headers? That prevents pasting parts of changelog as a section of another document (e.g. release notes), creates cacophony of fonts when converted to html, and is overall unnecessary because it adds no meaning nor reading convenience. It looks like this guy is overcomplicating quite a simple thing. I've been maintaining changelogs for pretty much all my career, in simpler format: -…

Indeed, your format looks exactly like what Perl's CHANGES spec stipulate: https://metacpan.org/pod/distribution/CPAN-Changes/lib/CPAN/...

Re: Keep a Changelog

#47

Post by theRhino » Wed, Feb 18, 2015, 11:35 AM UTC

note 'unreleased' is not the right word to use for the section above the last version. this is because a version is not necessarily a release. it should be called 'latest'