Nicely formatted changelogs are amazing for third-party tools: at requires.io we try to gather as many changelogs as possible, but oftentimes there are simply none available.
Keep a Changelog
11–20 of 47 posts
Re: Keep a Changelog
#12Projects 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 note that almost every CPAN module is on GitHub, and also almost every one has an up-to-date CHANGES file.
Re: Keep a Changelog
#13Projects 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 quite agree with this: the end goal of a CHANGELOG.md (or NEWS.md if you prefer) should be to give the end-user a summarized view of the changes since the last release, organized logically by order of importance, not chronologically by order of commit.
Something like: security issues, breaking changes, major features, major bugfixes, minor features, minor bugfixes.
Re: Keep a Changelog
#14"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.
Re: Keep a Changelog
#15Projects 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 agree with the argument that a NEWS file is the right thing here and already pretty close in spirit to what's being advocated. Among other things, "CHANGELOG" as a name evokes GNU-style ChangeLog files, which is the total opposite of what this site is advocating: https://sourceware.org/git/?p=glibc.git;a=blob;f=ChangeLog
But regarding git conflicts, I've set up dpkg-mergechangelogs as a global merge driver and it works decently well for cherry-picking things within Debian packages represented as git repos. In ~/.gitconfig:
[core]
attributesfile = ~/.gitattributes
[merge "dpkg-mergechangelogs"]
name = debian/changelog merge driver
driver = dpkg-mergechangelogs -m %O %A %B %A
debian/changelog merge=dpkg-mergechangelogs
Re: Keep a Changelog
#16I like projects that put their changelogs into git tags with `git tag -s`. On GitHub these even get shown by default on the releases page. A nice side effect is that you sign the hash of the release too.
Re: Keep a Changelog
#17Projects 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…
[deleted]
Re: Keep a Changelog
#18I just started using rf-release[1] to manage both maintaining a changelog and releasing to npm.
It maintains a CHANGELOG.md file that includes all the changes that have happened between version numbers. It chooses which commits to include by filtering on [added], [changed], [deleted], or [fixed]. Thus, if you'd like a change to appear in your changelog, just include one of those tags in the relevant commit message.
Seems like a nice way to prevent maintaining an npm package from becoming a chore.
Re: Keep a Changelog
#19I like projects that put their changelogs into git tags with `git tag -s`. On GitHub these even get shown by default on the releases page. A nice side effect is that you sign the hash of the release too.
> `git tag -s`
Know of somewhere that explains how to do that well? I'm a big fan of keeping all of my workflows related to project in git as much as possible, especially if GitHub picks it up correctly.
Re: Keep a Changelog
#20Projects 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…
In our case, we're writing "@changelog [quick summary of the change]" somewhere in our commit message when we think that the commit actually warrants a change log entry.
Then as part of the release process, somebody (usually me) uses `git log --grep` to find all the commit messages that developers thought to be change log relevant and writes a document that can be consumed by end users (including screenshots of the features etc).
This way end-users can still be informed about changes (most don't care, some notice and complain even when one pixel has moved to a different spot), but we never have issues with merges or rebases (at least not related to change log maintenance :p)
Also, in my opinion, keeping a change log for developers is completely unnecessary these days with git and other tools to provide very quick and easy access to the revision history.
But for end-users it still makes sense, though it of course has to be on a higher level than individual commits.