Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

CommitMessage Format (Git)

From TYPO3Wiki
Jump to: navigation, search

Commit Message rules for TYPO3 Flow

The commit message rules for TYPO3 Flow and Neos are described in the Flow documentation

Commit Message rules for TYPO3 CMS

Git and related tools work best when following a certain guideline for commit messages. A deeper introduction on git revision log conventions is helpful to understand the scope.

An example commit message looks like this:

[BUGFIX] Short summary of changes introduced by this patch

More detailed explanatory text, if necessary.  Wrap it to 74 characters.
The first line is treated as the subject of the commit message and 
the rest of the text as the body.  The blank line separating the 
subject from the body is critical (unless you omit the body entirely); 
tools like rebase can get confused if you run the two together.

Write your commit message in the imperative present tense ("Fix bug",
not "Fixed bug"). This convention matches up with generated 
commit messages by commands like git merge and git revert.

Help others to understand what you did (Motivation for the change?
Whats the difference to the previous version?), but keep it simple.

* Bullet points are okay, too
* An asterisk is used for the bullet, it can be preceded by a single
  space. This format is rendered correctly by Forge (redmine)
* Use a hanging indent

Resolves: #12345
Documentation: #12346
Releases: 6.2, 6.1, 6.0

As the commit message is kept in the history of the Git repository, please think of writing a proper message!

Topic description (first line)

  • Prefix the line with a proper tag: [BUGFIX], [FEATURE], [TASK] or [API].
  • Keep the whole line below 52 characters if possible, but below 80 in any case

Possible tags are:

  • [FEATURE]: A new feature (also small additions). Most likely it will be an added feature, but it could also be removed. This can only happen in v4's "master" branch, because no new features are allowed in older branches. Exceptions to this have to be discussed on a case-to-case basis with the corresponding release managers.
  • [BUGFIX]: A fix for a bug.
  • [TASK]: Anything not covered by the above categories, e.g. coding style cleanup.
  • [API]: An API has changed, methods or classes have been added or removed; method signatures or return types have changed. This only refers to the public API of TYPO3.

Additionally other flags might be added under certain circumstances:

  • [!!!]: Breaking change. After this patch, something works differently than before and the user / admin / extension developer will have to change something. Should only happen on "master".
  • [DB]: Something has changed in the database definition and would require a database COMPARE in the install tool after the update.
  • [CONF]: Some configuration changed. That could be a changed default value, a new setting or the removal of some setting that used to exist.
  • [WIP]: Work In Progress. This flag will be removed, once the final version of a change is available. Changes marked WIP are never merged.
  • [SECURITY]: Visualizes that a change fixes a security issue. This tag is used by the Security Team, in case you found a security issues please always follow get in contact with the Security Team first!

Example topic descriptions:

  • [BUGFIX] Throw HttpStatusExceptions in tslib_fe
  • [BUGFIX][SECURITY] SQL Injection vulnerability in prepared statements
  • [FEATURE][CONF] Add option to hide BE search box in list mod
  • [!!!][FEATURE] Move Advanced Frontend Editing to TER
  • [!!!][TASK] Remove t3lib_sqlengine
  • [!!!][API] Remove deprecated method redirect() from t3lib_userAuth
  • [API] Create an Exception hierarchy for HTTP Status Exceptions

Note: As in Flow, the [!!!] prefix is added at the very beginning of the line, so it doesn't get overlooked.

Message body

  • Describe the problem and the change introduced by the Change Request.
  • Keep it simple and don't repeat information that is already contained in the issue tracker. Especially avoid "How to reproduce" part. At most, try to explain the change itself, if it is not already clear by reading the diff.
  • Wrap the lines after 72 characters manually
  • Write your commit message in the imperative present tense ("Fix bug" and not "Fixed bug"), since a commit is a set of instructions for how to go from a previous state to the new state and the commit message should describe this process. This convention matches up with generated commit messages by commands like git merge and git revert.

Relationships

Important: The space after the colon (:) is mandatory. Otherwise the system will not properly update forge.

  • Refer to the bug tracker entry (features and tasks, closes the issue on submit) (on http://forge.typo3.org):
    Resolves: #12345
    • Deprecated: Some issues from the time since the introduction of GIT (March 1st 2011) and the migration of the bug tracker to Forge (March 29th 2011), still refer to Mantis bug tracker numbers, with a prefix the number with an M, i.e.
      Resolves: #M12345
  • Refer to the bug tracker entry (all types, simply a relation, no closing) (on http://forge.typo3.org):
    Related: #12345
  • Refer to the branches for which this change will apply:
    This should be done on bugfixes which should be backported to older releases. Always write the number of the release, not a branch like "master", because it will be difficult later to check, when the code was branched and which releases were made out of it. Not used for FLOW3 (yet).
    Releases: 6.1, 6.0, 4.7, 4.5
  • For [FEATURE] patches, the Documentation line is mandatory and refers to corresponding documentation ticket.
    Documentation: #12345
  • For TYPO3 documentation patches, refer to the corresponding TYPO3 Core patch:
    Depends: ChangeIdOfCorePatch

If you have multiple resolved or related issues, use one line for each issue number.

Time Tracking

If you want your project to be able to track time you need to enable the time tracking feature in the settings of your Forge Project and just add the time you worked to your commit message, like:

Resolves: #12345 @1h:30

Reverting patches

If there's the need to revert a patch, please add this information to the commit message:

  1. a Resolves-line for the ticket with reason for the revert
  2. a Reverts-line for the ticket of the original patch

Commit Template

You can use a custom template for getting the commit message faster done.

All you need is the template like

[BUGFIX|TASK]

Resolves:
Releases:

in a file, e.g. ~/.gitmessage.txt

and the command

git config --global commit.template ~/.gitmessage.txt