Commit Message Style

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 :slight_smile:

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 needed If the change resolves a ticket by fixing a bug, implemeting a feature or doing a task.
    • <issue number> #comment Some info why this is related If 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)

4 Likes

Since we create the change log from PR merges by now, we could use the labels on GitHub as well and do away with the tags completely, leaving only the !!! marker for added clarity. Or we just don’t care about those tags at all, and just look at the issues that have been fxed for a release. If we stick to them, we could also keep the square brackets, it’s just a detail.

And regarding the tools controlling us: Well… this has evolved over the case of years and the dropping of suqare brackets has at least as good a reason as we have using them.

Since we create the change log from PR merges by now, we could use the
labels on GitHub as well and do away with the tags completely, leaving
only the !!! marker for added clarity

This part is still undecided, especially as we are now completely on github, so is that a way to go? Can we actually get the labels from the API?

You can through a separate call https://api.github.com/repos/neos/neos-development-collection/issues/1211/labels