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:

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.

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.

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

Automatic version info

To have Information about Fileversion, author and commitdate automatically generated on commit. You must do three Things.

• Put the GPL Info and the Id tag into your new or unversionized file. It always looks like this:

/*
* LimeSurvey
* Copyright (C) 2007 The LimeSurvey Project Team / Carsten Schmitz
* All rights reserved.
* License: GNU/GPL License v2 or later, see LICENSE.php
* LimeSurvey is free software. This version may have been modified pursuant
* to the GNU General Public License, and as distributed it includes or
* is derivative of works licensed under the GNU General Public License or
* other free or open source software licenses.
* See COPYRIGHT.php for copyright notices and details.
*
* $Id$
*
*/

The important Tag is the $Id$, which will be replaced with the version info.

• Assuming you use TortoiseSVN, go to the folder with you newly created or unversioned file and right-click on the file.
  • Under the Context-Menu "TortoiseSVN" you will find the Option "Properties". Go to the Properties.
  • Now you see an empty list with Options New and Import(others are not clickable).
  • Choose "new".
  • Choose "svn:keyword" from the Property-Name-Dropdown-Menu and
  • type "Id" as value.
  • Click OK.
• Or if you use terminal, you can run the command:

svn propset svn:keywords "Id" file.php

• Now commit the file... and voila! The new file is versionized.