DevHeads.net

Unified git commit message guideline

For KWin we think about a message guideline because our current best
practice that we got used to over time is just sometimes putting tags
in square brackets at the beginning of the subject line for indicating
the location of the change in code but somebody noted having a square
bracket in the beginning leads to problems with certain git log parser
tools.

Asking around on IRC it seems we should expand the scope. Apparently
also other KDE projects could profit from a policy and some tooling
around it. We currently have the Phabricator commit message formatting
through arc, but this doesn't expand to the important subject line and
it will go away soon anyway with our move to GitLab.

After looking around a bit what I found to be very interesting was the
Conventional Commits specification[1]. It is based on the AngularJS
commit message policy, which is imo a very well formulated policy.

Besides the policy they offer also several tools to check own commits
and to be integrated into a CI system: there is commitlint[2] to check
commits on obeying the policy and conventional-changelog[3] to create
changelog documents automatically from these commits.

For example looking at the latest changelog of Frameworks[4] in the
long list of commits there is no differentiation between fixes,
features and other work. Also sometimes there are tags, sometimes not,
and if there are sometimes they are in square brackets, sometimes with
colons.

In contrast a changelog generated from commits following the
conventional commits specification can be easily sorted and
reformatted. An example for that is Angular's changelog[5].

What do you think about such a guideline? Would an admin be interested
in putting these tools onto a test instance? I know admins currently
have much to do with GitLab transition though, so I write this message
also as a reminder to myself to pick it up again afterwards if there
is no time right now.

[1] <a href="https://www.conventionalcommits.org" title="https://www.conventionalcommits.org">https://www.conventionalcommits.org</a>
[2] <a href="https://commitlint.js.org" title="https://commitlint.js.org">https://commitlint.js.org</a>
[3] <a href="https://github.com/conventional-changelog/conventional-changelog" title="https://github.com/conventional-changelog/conventional-changelog">https://github.com/conventional-changelog/conventional-changelog</a>
[4] <a href="https://kde.org/announcements/kde-frameworks-5.61.0.php" title="https://kde.org/announcements/kde-frameworks-5.61.0.php">https://kde.org/announcements/kde-frameworks-5.61.0.php</a>
[5] <a href="https://github.com/angular/angular/blob/master/CHANGELOG.md" title="https://github.com/angular/angular/blob/master/CHANGELOG.md">https://github.com/angular/angular/blob/master/CHANGELOG.md</a>