Keep the changelog, avoid the conflicts

I don’t really like the keep-a-changelog idea. Most changelogs get rewritten on release anyway so the main branch’s changelog becomes its own meta-branch of half-baked language that only reaches production state when the release is finalized. Something about that doesn’t sit well with a codebase where everything else has to be production ready all of the time. Where else do you accumulate temporary code/code-like features that need editing and annealing before the code is production ready?

If you have a part of your codebase that’s constantly suffering from merge conflicts then for me that’s a sign that something more fundamental isn’t working. Throwing more code at the problem feels like a hack.

Would you block a change that looked good but had the wrong language for the release notes that was rejected by the person responsible for the release? If one person writes the code and another person releases it, shouldn’t these be two commits anyway?

Perhaps your changelog is for internal use to explain why the codebase changed and when? Why is that not documented in your commit history and instead kept in a mutable part of the codebase?

If you kept each log entry in a file (do people do changelog.d and treat release notes as a compilation step?) then new log entries never conflict and a commit that edits an existing log entry will correctly flag as a conflict with anyone else who made an edit. No tool needed.

I think though, in all honesty, these kinds of ideas are hard to land well. I’m wary of dogmatic advice that — by definition as being a do-this-thing.com — is broadcast-only with a lack of any local context.

(To the author, given that this appears to be a Show HN: although I don’t think this stands up as a general purpose tool, it’s a nice solution and a good example for what a automated merge tool can look like.)

Some projects, like CPython, collect changelog entries as individual files with random names in a dedicated directory. Then, a script assembles the changelog at release time. I always thought this was a nice and elegant solution: in some sense, a changelog is a list with no special merge handling, but a directory is a list (of files) that does have special merge handling, so you just use that as your substrate.

I enjoy using Semantic Release (https://semantic-release.org/) for publishing NPM packages and creating the corresponding changelog on release. In the mean time on the beta working branch and in general you can just read the commit messages for a similar overview.

It does require care when preparing your work and the necessary conventional commit messages (https://www.conventionalcommits.org/).

IMO, a changelog should only be updated once the PR has been checked and validated and gone through all the appropriate CI/CD processes, and finally merged to the main branch. Then you can point at the PR for all their work that was done, with a brief summary in the changelog.