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

21–30 of 47 posts

Re: Keep a Changelog

#21

Post by leni536 »

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 practice to manage change logs in a repo. I'm sure that it shouldn't be in a project's git repo though. Maybe having a separate git repo for managing releases would help, like have your original project as a submodule and keep release specific files in this separate repo. Obviously it looks more complicated but it's better than managing merge conflicts between CHANGELOG files when there is no meaning of the CHANGELOG for the merge commit anyway.

Re: Keep a Changelog

#22

Post by j0k3r »

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…

Gitlab guys found a working method to fight the git conflict on the CHANGELOG file: https://about.gitlab.com/2015/02/10/gitlab-reduced-merge-con...

Sumup:

> At GitLab we solved the above problem by adding a 100 lines with just a hyphen placeholder at the top of the changelog. People can insert their entry at a random location in the changelog. There is still a chance of conflict when two merge requests change the same line but it is greatly reduced. It looks a bit strange to have these empty lines on top so we added a comment to explain their purpose..

Re: Keep a Changelog

#23

Post by Terr_ »

nirvdrum wrote: post #14
tomphoolery wrote: post #8

"Because log diffs are full of noise. Can we really expect every single commit in an open source project to be meaningful and self-explanatory? That seems like a pipe dream." I thought this was the point of squashing your commits together when making a pull request, so the `git log` of master reads like a changelog. You can also interactively rebase and change commit messages if the wording is confusing.

The definition of "meaningful" might be a bit soft here. When figuring out what changed in a release, I don't really care that you "converted tabs to spaces" or "refactored method name based on intent" or any such structural change. The git log is generally too noisy to be used for describing a release.

Exactly: There are two very different use-cases and audiences.

Your version-control system should be helping programmers understand the evolution of the codebase, or the reasons behind certain line-changes... especially when those changes were made by someone else long ago.

The changelog, on the other hand, is for a less-technical (or at least less-involved) audience. It has to summarize the net-change which occurs in a way which is meaningful to people asking different sets of questions. Such as: "What are the new features?" and "Did they change anything about X?"

Re: Keep a Changelog

#24

Post by alexatkeplar »

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…

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

It's actually pretty simple - you keep CHANGELOG updates to their own commit, and just aggressively rebase into that commit as you prepare the release. The release owner is the only person who works on the CHANGELOG. We do that at Snowplow and it works really well. Here is the WIP commit for the CHANGELOG for the next Snowplow release: https://github.com/snowplow/snowplow/commit/a862b1e4ab935184...

When we finish a release, the CHANGELOG becomes the GitHub release notes: https://github.com/snowplow/snowplow/releases/tag/r60-bee-hu...

We are approaching 1 issue : 1 commit : 1 CHANGELOG entry but it's not always possible, and a huge number of open source software users are not technical enough to parse a git log anyway.

Re: Keep a Changelog

#25

Post by Benjamin_Dobell »

From the article:

Is there a standard change log format?

Sadly, no. But I want to change that.

... wait, what?

There are plenty of standardised change log formats. Take for example Debian's changelog format:

https://www.debian.org/doc/debian-policy/ch-source.html#s-dp...

Or are they talking about one standard to rule them all? In which case...

http://xkcd.com/927/

Re: Keep a Changelog

#26

Post by [deleted] »

viraptor wrote: post #10

> Is there a standard change log format? Sadly, no. But I want to change that. What's missing from some formats which already exist and are pretty popular? https://www.debian.org/doc/debian-policy/ch-source.html describes debian changelog format which applies to all .deb packages for years now.

[deleted]

Re: Keep a Changelog

#27

Post by teddyh »

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

Re: Keep a Changelog

#28

Post by rquirk »

j0k3r wrote: post #22
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…

Gitlab guys found a working method to fight the git conflict on the CHANGELOG file: https://about.gitlab.com/2015/02/10/gitlab-reduced-merge-con... Sumup: > At GitLab we solved the above problem by adding a 100 lines with just a hyphen placeholder at the top of the changelog. People can insert their entry at a random location in the changelog. There is still a chance of conflict when two merge requests change the sam…

Seems they no longer use this method. Instead they use `CHANGELOG merge=union` in a .gitattributes file at the root of the repository. That means that conflicting merges take changes from both sides of the conflict. It's what you usually want with a changelog.

Re: Keep a Changelog

#29

Post by hamstergene »

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:

    - at the top of file go unreleased changes, without a header

    1.6.1: 2005-01-22
    - fixed: one
    - fixed: another

    1.6: 2004-11-18
    - fixed: this
    - added: that
    - redesigned preferences dialog
There is zero markup noise here, and when interpreted as markdown it looks just as nice.

Re: Keep a Changelog

#30

Post by Moru »

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…

not invented here-syndrome
Post reply on HN