Standard for Git commit messages: Difference between revisions
From LimeSurvey Manual
No edit summary |
m (corrected standard for security commit message) |
||
| (29 intermediate revisions by 7 users not shown) | |||
| Line 1: | Line 1: | ||
__TOC__ | __TOC__ | ||
=General overview= | =General overview= | ||
This page describes the standard format of commit messages. Indeed, standard commit messages will | 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= | =Rules= | ||
| Line 11: | Line 11: | ||
* Each commit message is made up of one or more commit blocks | * Each commit message is made up of one or more commit blocks | ||
* A commit block: | * A commit block: | ||
** The first line is the 'Commit Summary' and describes the committed patch in a user friendly way | ** 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 | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="text"><Commit type>: <commit label> <commit description> <NEWLINE> | ||
[ Dev <development details> <NEWLINE> ] | [ Dev <development details> <NEWLINE> ] | ||
| Line 20: | Line 20: | ||
[ Dev <development details> <NEWLINE> ] | [ Dev <development details> <NEWLINE> ] | ||
<Commit type> <commit description> <NEWLINE> | <Commit type>: <commit label> <commit description> <NEWLINE> | ||
[ Dev <development details> <NEWLINE> ] | [ Dev <development details> <NEWLINE> ] | ||
| Line 29: | Line 29: | ||
The first word in the commit message gives 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 '''' | * 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 | * 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 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 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 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 : <code>Fixed issue #1234: [security] Persistent XSS</code> | |||
==The commit description== | ==The commit description== | ||
Following the commit type is 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. | |||
Ideally it is a text readable by end-users: for instance if you're resolving a bug ticket | |||
==The development details== | ==The development details== | ||
Develoment details are added in extra | Develoment details are added in extra optional lines, each one beginning with the keyword ''''Dev''''. | ||
==Patches which require multiple commits== | ==Patches which require multiple commits== | ||
| Line 51: | Line 56: | ||
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. | 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 | == Examples== | ||
Example of a simple language file update: | Example of a simple language file update: | ||
<syntaxhighlight lang=" | <syntaxhighlight lang="text">Updated translation: German</syntaxhighlight> | ||
Example of a security fix: | |||
<syntaxhighlight lang="text">Fixed issue #9762: [security] XSS possible</syntaxhighlight> | |||
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 | <syntaxhighlight lang="text">Fixed issue #2565: Can't access survey more than once on the same browser window | ||
Dev | Dev: This fixes this bug for survey with tokens. | ||
Dev | Dev: When showing a new token (different from the one in session), the previous session is destroyed.</syntaxhighlight> | ||
Commit 2: | |||
<syntaxhighlight lang=" | <syntaxhighlight lang="text"> | ||
Fixed issue #2565: Can't access survey more than once on the same browser window | |||
Dev | Dev: This fixes this bug for survey without tokens and without answer preview. | ||
Dev: Session is destroyed at submit time.</syntaxhighlight> | |||
Commit 3: | |||
<syntaxhighlight lang="text">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 | Dev: Session is destroyed when closing the answer preview window or closing the Submit confirmation page.</syntaxhighlight> | ||
Example of a single commit containing several fixes each with a Dev comment: | |||
<syntaxhighlight lang="text">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</syntaxhighlight> | ||
[[Category:Development]] | |||
Latest revision as of 16:28, 26 July 2023
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