Non-automated change log

[killercup]

The book currently mentions clog. As a manual alternative, I like using http://keepachangelog.com.

In crate-ci/crate-ci.github.io#5 (comment), @epage wrote:

Kind of fun that the reason I got started with clog is your blog post. How come you have switched away from it?

I do like the idea of having the commit messages be a single source of truth for the change log. And I do like writing very long commit messages.

More often than not who you write a change log for is not who you write a commit message for, however. The change log will be read by the users of your project, while the commit messages will be read by contributors to it. (Or, well, users who had to dig through your code because your docs/change log were not helpful enough!)

So, to give an example, this change log entry:

The full code of the example projects from the guides is now also available in the repository's examples/ directory.

is part of a commit with this commit message:

Add example code from guides part of the repo

This changes the call to waltz to render the code from the guides into
the examples/ directory instead of a some temporary directory and
assert that they are checked in.

Or, a more extreme example: Check out this change log entry describing how to upgrade to the new version. This is a format you can't produce with clog.

---

tl;dr Using clog is better then having no change log. But if you go through all the trouble of formatting you commit messages in a certain way, you can probably also write change log entries in a user-facing manner.

[epage]

@CAD97 I assume you are in favor of this :)

[CAD97]

Yep, I'm a big fan of Keeping a Changelog.

One of my favorite features of the Keep a Changelog format is that it makes access to the Git history simple to access; the commit granular changelog can be viewed by viewing the git log, and if you're writing quality commit messages and telling a clean history with your commits, it will be a clean story.

I think the guidelines we should consider teaching on top of Keep a Changelog's philosophy is basically just "Each PR should update the [Unreleased] section of the changelog before being merged if it includes user-facing changes, which could be API changes, fixes, or even internal changes observable through performance."

... Speaking of, I just realized I need to add dates on to the changelog for ghp-upload....