Standard for Git commit messages

General overview

This page describes the standard format of commit messages. Indeed, standard commit messages will make sure that the automatic generation of releases change logs will work properly. If you do not follow these rules your contribution(s) might not be properly credited in the change log.

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 label> <commit description> <NEWLINE>

[ Dev <development details> <NEWLINE> ]

[ Dev <development details> <NEWLINE> ]

<Commit type>: <commit label> <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 #<bug ID without leading zeros>' or if there is no bug ID just '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'
• If the commit is not connected to any tracker issue and not of public interest (changelog), just pure development then use 'Dev'

The commit label : security

If commit is a security fix, add "[security]" label to first line commit description like in the example below.

Example : Fixed issue #1234: [security] Persistent XSS

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 give the commit a user-friendly description and make sure it describes the problem, not the solution. Remember that an end-user would scan the log that way for a fix for his/her specific problem.

The development details

Develoment details are added in extra optional 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.

The development details (line starting with the keyword 'Dev') can differ, of course.

Examples

Example of a simple language file update:

Updated translation: German

Example of a security fix:

Fixed issue #9762: [security] XSS possible

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