To have a clear and focused history of code changes is greatly helped by using a
consistent way of writing commit messages. Because of this and to help with (partly)
automated generation of change logs for each release we have defined a fixed syntax for
commit messages that is to be used.
Tip: Never commit without a commit message explaining the commit
The syntax is as follows:
- Start with one of the following codes:
FEATURE
A feature change. Most likely it will be an added feature, but it could also be removed. There should
be a corresponding ticket in the issue tracker. Features usually only get into the current development master.
BUGFIX
A fix for a bug. There should be a ticket corresponding to this in the issue tracker and we encourage to add a new test that exposes the bug, which makes the work for everyone easier in the future and prevents the bug from reappearing.
TASK
Anything not covered by the above categories, e.g. coding style cleanup or documentation changes. Usually only used if there’s no corresponding ticket.
SECURITY
A security related change. Those are only commited by active team members in the security community of practice.
MERGE
Used for a branch upmerges by the team (or CI server) not something you usually would need to use.
-
The code is separated by a colon
:from a short summary in the same line, no full stop at the end. -
If the change affects the public API or is likely to break things on the user side, prefix the line with
!!!. This indicates a breaking change that needs human action when updating. Make sure to explain why a change is breaking and in what circumstances. A change including a migration should always be marked breaking to alert users of the need to migrate (3). -
Then (after a blank line) follows the custom message explaining what was done.
It should be written in a style that serves well for a change log read by users.
If there is more to say about a change add a new paragraph with background information below.
In case of breaking changes give a hint on what needs to be changed by the user.
If corresponding tickets exist, mention the ticket number(s) using footer lines after another blank line and use the following actions:<issue number> #close Some additional info if neededIf the change resolves a ticket by fixing a bug, implemeting a feature or doing a task.<issue number> #comment Some info why this is relatedIf the change relates to an issue but does not resolve or fix it.
This follows Jiras smart commit footers, see more details in the Jira documentation
A commit messages following the rules…:
TASK: Short (50 chars or less) summary of changes
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary 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 present tense: "Fix bug" and not "Fixed
bug." This convention matches up with commit messages generated by
commands like git merge and git revert.
Code snippets::
should be written in
ReStructuredText compatible
format for better highlighting
Further paragraphs come after blank lines.
* 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
A first step in solving neos/flow-development-collection#789.
Fixes #123
Closes #456
Examples of good and bad subject lines:
Introduce xyz service
BAD, missing code prefix
BUGFIX: Fixed bug xyz
BAD, subject should be written in present tense
TASK!!!: A breaking change
BAD, subject has to start with !!! for breaking changes
BUGFIX: SessionManager removes expired sessions
GOOD, the line explains what the change does, not what the bug is about (this should be explained in the following lines and in the related bug tracker ticket)
!!! BUGFIX: SessionManager never expires sessions
GOOD, the line explains what the change does, not what the bug is about (this should be explained in the following lines and in the related bug tracker ticket)