Keep a Changelog
keepachangelog.com
Keep a Changelog
1–10 of 47 posts
Re: Keep a Changelog
#2> Dumping a diff of commit logs. Just don’t do that, you’re helping nobody.
Depending on how you write your comments for commits, merges, or tags, it seems that you could dump those logs and have quite a reasonable changelog.
Re: Keep a Changelog
#3I follow this set though I hadn't read about it before. I do one additional tag that is not mentioned. "Updated", which is used for translations. So, each release has a line similar to this:
Updated: French, Portuguese Brazilian, Spanish International
It doesn't affect the app other than those specific translations and it makes it easy to pinpoint when a given translation was last updated.
Re: Keep a Changelog
#4> Dumping a diff of commit logs. Just don’t do that, you’re helping nobody. Depending on how you write your comments for commits, merges, or tags, it seems that you could dump those logs and have quite a reasonable changelog.
I think a good approach to this when using git, that I've tried to keep in my own projects of late, is to keep your master branch only merge commits and curate the merge commit messages explicitly to be human readable descriptions of the changes. I think it's entirely possible to generate good changelogs out of this and proper tagging, but there probably need to be a few less awkward tools for maintaining it than just directly using git commands.
Re: Keep a Changelog
#5In Perl a standard had evolved[1] that is a bit less structured, but designed to be machine read/writable while still being human centered.
And if you build your distributions with Dist::Zilla[2] you can use plugins to ensure that you have an entry for your release[3] and that the changelog follows the standard[4].
[1] https://metacpan.org/pod/distribution/CPAN-Changes/lib/CPAN/...
[2] https://metacpan.org/pod/Dist::Zilla
[3] https://metacpan.org/pod/Dist::Zilla::Plugin::CheckChangesHa...
[4] https://metacpan.org/pod/Dist::Zilla::Plugin::Test::CPAN::Ch...
Re: Keep a Changelog
#6It's worth noting that they link to Vandamme, the library used by Gemnasium for parsing changelogs, but Vandamme recommends a slightly different format for the file:
https://github.com/tech-angels/vandamme/#changelogs-conventi...
I prefer Vandamme's recommended format, but I'd greatly appreciate this site's format as well.
Re: Keep a Changelog
#7Good issue tracking tools can produce changelogs for you, which is preferable to maintaining a redundant, separate log manually. It also encourages good practices like tracking all user-visible changes and keeping issue summaries accurate and readable.
Re: Keep a Changelog
#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.
Re: Keep a Changelog
#9Projects 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 more logical commits; once you stop breaking "git rebase -i", that gets a lot easier.
Some of this advice potentially makes sense, but for a NEWS file, not a changelog. A NEWS file has one top-level heading per release, containing the release notes for that release, summarizing the key user-visible changes. However, that file should not attempt to track every change, should not contain times or dates, and should get grouped in logical chunks rather than chronological order.
And while it can potentially make sense to update that file as part of the commit introducing a new user-visible change, that also reintroduces the same conflict and collaboration issues as a changelog, so personally I only update NEWS files right before a release. I run a script that generates a properly formatted NEWS entry based on the version and git commit messages (turning each one into a markdown bullet-list entry with indentation), then edit the result to add headings, group entries under those headings, and delete any non-user-visible changes that don't merit a release note.
Re: Keep a Changelog
#10 > Is there a standard change log format?
Sadly, no. But I want to change that.