Question: good process for keeping changelogs in a team

[dskrvk]

I'd like to request a section describing some good (and working) practices around teams keeping changelogs.

E.g. in my team we mostly use the git log as a source for changelogs, prefixing every commit title with tags such as [feature], [bug], [test] etc., then lightly editing the changelog to remove redundant entries, add missing tags, or reword some titles. We have scripts that collect and format the git logs since the last release, but currently the process requires 1. discipline from the committers, 2. (a bit of) manual effort from the release manager.

I have also seen the Gitlab's guide, but that requires each contributor to create a specially-formatted file in addition to writing a good commit message. Perhaps that is a better way, I'm not sure.

[michaeltlombardi]

We have a requirement that PRs must include a relevant entry in the unreleased section of the changelog if targeting master (if an entry is needed for the code). This helps us ensure the person most familiar with the changes is helping to write the changelog while it's still fresh instead of trying to go back in time later. It also shortens our release process and helps us decide when it makes sense to do a release. Finally, it gives our users and team members a chance to see what we've been working on between releases without having to check the commit logs which are written specifically with the maintainers in mind.

We don't always remember to update the changelog but we're getting better about it and have found it widely useful for our projects.

[MHebes]

I will second this old question. How do you handle merge conflicts between two open PRs that both add a changelog entry? Ideally without needing all the machinery that GitLab has added for their changelog.

[axd1967]

Updating the changelog as part of a branch is logical, but might sometimes need redaction after the merge to master (eg to accomodate for a different format - not every contributor might be aware of the requirements of the changelog - or e.g. to make it more succint).

Merge conflicts are very likely to happen , and are to be solved when the feature branch is merged.

Note: a distinction should be made between commit messages and changelog changes.

The commit message should allow anyone being unable to apply the change, to recreate it (e.g. changes in diagrams, but the graphical editor is not able to perform merging).

The changelog message should be more high level (directed towards the end user)

It could be problematic to generate changelogs automatically from commit messages, as this introduces a file that is redundant from a VCS point of view; this approach could force the committer to write in "end user" style, while the committer is typically the developer that writes commit messages for the benefit of other developers.

[webknjaz]

I will second this old question. How do you handle merge conflicts between two open PRs that both add a changelog entry? Ideally without needing all the machinery that GitLab has added for their changelog.

In many of my projects, I use a tool that is popular across the Python community — Towncrier. The idea is that every pull request must include a text file with a changelog fragment (or a note), that file would have a PR or an issue number in its name, followed by a category identifier. There can be more than one fragment in a PR, if needed. The content of that file must use the same markup syntax as the main changelog file (like RST or MD). With separate change notes, it's virtually impossible to run into conflicts, plus this gives the reviewers a chance to check what will go into the changelog as well. Throughout the development cycle, those notes are just accumulated in Git. When it's time to make a release, the maintainers run towncrier and it adds a new release entry in the main changelog file deleting the fragment files, it's an atomic move. The template for that release section as well as acceptable categories are customizable.
Although, external contributors usually need some guidance. So here's what I usually add to the contributing docs: https://setuptools.pypa.io/en/latest/development/developer-guide.html#adding-change-notes-with-your-prs.
Here's an example of the rendered changelog: https://setuptools.pypa.io/en/latest/history.html#v59-0-0 (the same thing in Git: https://github.com/pypa/setuptools/blob/main/CHANGES.rst#v5900).