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>

Comments

Re: Unified git commit message guideline

By Marc Deop =?ISO... at 08/22/2019 - 12:55

On Sunday, 11 August 2019 23:52:55 CEST Roman Gilg wrote:
Please make sure to consider Git Karma [1]

[1] <a href="http://karma-runner.github.io/4.0/dev/git-commit-msg.html" title="http://karma-runner.github.io/4.0/dev/git-commit-msg.html">http://karma-runner.github.io/4.0/dev/git-commit-msg.html</a>

Re: Unified git commit message guideline

By David Faure at 08/12/2019 - 02:44

Hello Roman,

On dimanche 11 août 2019 23:52:55 CEST Roman Gilg wrote:
I like the idea very much, the changelog does look a bit messy indeed.
It would allow me to filter out all style, ci, and test changes, which are not
interesting to the user of the frameworks.

I'm missing a type for internal cleanups like porting away from deprecated
methods or fixing a harmless compiler warning? OTOH "chore" isn't documented
in the Angular convention so I don't know what it is. In any case, it sounds
like we need to write down our own list of types, right?

I would also like to keep the "Test Plan" field from phab even after we move
to gitlab, it pushes people to write down how they actually tested the change.

I think we should wait until after the switch to gitlab though, because it
might have some influence on this. For instance with phab I tend to prefix the
subject with the repo name so that on k-f-d we can see which framework it's
about. But that looks a bit redundant in the git history of a given repo
afterwards so if the emails from gitlab include the repo name automatically,
we shouldn't do that in the git commit log itself.

Re: Unified git commit message guideline

By Simon Redman at 08/14/2019 - 21:25

On 8/12/19 12:44 AM, David Faure wrote:
For better or for worse, this doesn't make it in to the commit message
by default, though

<a href="https://invent.kde.org/kde/kdeconnect-kde/blob/master/.gitlab/merge_request_templates/Feature.md" title="https://invent.kde.org/kde/kdeconnect-kde/blob/master/.gitlab/merge_request_templates/Feature.md">https://invent.kde.org/kde/kdeconnect-kde/blob/master/.gitlab/merge_requ...</a>