Skip to content

Determine if we can use commit titles to generate changelog entries

Introduction

In &351 (closed) we are writing up a proposal to change the way we generate/maintain changelogs at GitLab, for all our projects (GitLab, Gitaly, etc).

Our current setup is as follows: when creating merge requests, authors generate a YAML file in changelogs/unreleased. When Release Tools creates a release, it merges these files into a CHANGELOG.md file, them removes these entry files.

The goal of the mentioned epic is to find a way that makes this process easier for our developers, ideally using functionality that already exists in GitLab or that we build into GitLab; allowing other GitLab users to make use of this functionality for their own projects.

Populating changelog data with commit titles

Changelog entries are currently written manually. This requires developers to describe their changes in three different places:

  1. In the merge request title/description
  2. In their commit messages
  3. In the changelog entry file

We want to move to a setup where we can reduce this duplication.

An approach we could take is to have GitLab automatically figure out which merge requests were included in a release, and use that to populate release data. This creates a problem though: when we perform security releases, all work happens in private security mirrors. Thus, if we were to have GitLab generate release notes/changelog data for the public projects, it wouldn't be able to include the data from the security mirrors.

Issues have a similar problem: they stay closed until a few days after a security release, meaning we can't show them when we generate a changelog/release.

The only data that we have available across projects are commits, as at the end of a security release we merge these from the security mirrors back into the public projects. This would allow us to populate changelogs based on commit titles, and perhaps further enhance that in the future with additional data (e.g. the merge requests that created those commits, if we can find them).

An added benefit is that you no longer need to maintain changelog entry files. In addition, we may be able to populate merge request titles or descriptions with the commit data (right now our MR templates make this difficult, but we could solve that somehow). This means that one day you only need to write your changelog entry title in one place, instead of three.

This brings us to the following questions that we need to answer:

  1. Are we as an organisation OK with requiring developers to write reasonable commit titles, so that we can use these to generate changelogs?
  2. Are we OK with imposing a few additional restrictions on what commit messages we allow merging, such as not allowing merging of "Applied feedback to X" commits?

For the first question, keep in mind that we are not requiring users to write an entire book in their commit message. Instead, we are asking if we are OK with enforcing commit messages to be more like this, and less like this.

NOTE: these are just random commits I picked to illustrate what we are looking for.

The second question is worth clarifying: if we use commits to generate changelogs, we want to exclude certain commits such as "Applied feedback to README.md" commits. While we at some point may be able to build a feature in GitLab to filter these out when generating changelogs, it's much easier if they are never merged in the first place.

In practical terms this means one of two things need to happen when it comes to commit messages and merge requests:

  1. Developers need to squash/rebase their commits before assigning them for review. This way reviewers review what is actually intended to be merged.
  2. Alternatively we require the use of squash on merge. This is not ideal as we may lose useful individual commits, but it serves as a backup option.

To help us answer this question, please take the following steps:

  1. If you are OK with what we propose above, you can upvote the issue with the 👍 reaction.
  2. If you are not OK with the proposal, please react with 👎 emoji and leave a comment explaining why. The comment in particular is important, as it helps us understand your decision better.

For more details about what we are considering and the ins and outs, please take a look at the epic mentioned above.

Edited by Yorick Peterse