Standard for Git commit messages

General overview

This page describes the standard format of commit messages. Indeed, standard commit messages will ease the automatic generation of releases change logs.

Rules

Syntax

• Each commit message is made up of one or more commit blocks
• A commit block:
  • The first line is the 'Commit Summary' and describes the committed patch in a user friendly way
  • The following lines begin with the Keyword Dev and are intended to the developpers team

<Commit type> <commit description> <NEWLINE>

[ Dev <development details> <NEWLINE> ]

[ Dev <development details> <NEWLINE> ]

<Commit type> <commit description> <NEWLINE>

[ Dev <development details> <NEWLINE> ]

[ Dev <development details> <NEWLINE> ]

The commit type

The first word in the commit message gives the commit type:

• If the commit is about a fix, the commit message must begin with the keyword 'Fixed issue'
• If the commit is about a change in LS feature, the commit message must begin with the keyword 'Updated feature'
• If the commit is about a change in a translation, the commit message must begin with the keyword 'Updated translation'
• If the commit is about a new feature, the commit message must begin with the keyword 'New feature'
• If the commit is about a new translation, the commit message must begin with the keyword 'New translation'

The commit description

Following the commit type is the commit description.

This must be a single line (no newline character), and is intended to be used in the generated changelog.

Ideally it is a text readable by end-users: for instance if you're resolving a bug ticket which has a very technical description, please use a "end-user friendly description".

The development details

Develoment details are added in extra optionnal lines, each one beginning with the keyword 'Dev'.

Patches which require multiple commits

When multiple commits are linked to the same topic (same new feature, same fix, ...), the 'Commit Summary' line of subsequent commits must be the same as the one provided for the first commit.

Of course the development details can differ.

Examples

Example of a simple language file update:

Updated translation: German

Example of a single bug which is fixed in several commits:

Commit 1:

Fixed issue #2565: Can't access survey more than once on the same browser window

Dev this fixes this bug for survey with tokens.

Dev When showing a new token (different from the one in session), the previous session is destroyed.

Commit 2:

Fixed issue #2565: Can't access survey more than once on the same browser window

Dev This fixes this bug for survey without tokens and without answer preview.

Dev Session is destroyed at submit time.

Commit 3:

Fixed issue #2565: Can't access survey more than once on the same browser window

Dev This fixes this bug for survey without tokens and with answer preview.

Dev Session is destroyed when closing the answer preview window or closing the Submit confirmation page.

Example of a single commit containing several fixes each with a Dev comment:

Fixed issue #1234: Fixed some untranslated strings

Dev Missing call to clang-gT in admin.php

Fixed issue #2345: Fixed a small layout issue in condition editor

Dev Fixed div HTML elements