Git Guidelines

Motivation

The commit history and especially the commit messages are part of a project’s documentation. Therefore, the same rules that are valid for documentation are also valid for commits and commit messages. A commit message is written once, but read many times (especially when hunting bugs). Git supports powerful tools to find out which commit introduced a bug (e.g., git bisect, git blame). Their level of usefulness depends on the quality of the commits and their respective commit messages.

Git Configuration

Since name and e-mail address are part of the commit (and thus be part of the commit history) they shall be specified via the .gitconfig file. So this file must at least include the following lines:

[user]
email = <your-email-address> (e.g. max.mustermann@something.com)
name = Max Mustermann

Commit History

Before merging a PR all commits shall be squashed into few (desired only one) logical commits.

Note

Keep in mind that upon merge the commit history of your branch will be preserved in the main branch of the repo as well.

Commit Message Format

In Score it is checked if git commit messages are written according to guidelines. However, it cannot enforce the meaningfulness of the message (and its parts).

Note

Remember that this information is shown in git log and other tools.

Wording

Proper English language and full sentences are to be used in the commit message. For both the subject and the body a singular imperative form is required. E.g. “Add unit test for class XY” and not “I added unit tests”, “Adding unit tests” or “Various minor changes”.

Additionally, the following specification for the content shall apply for commit messages (according to [Eclipse Git Commit Records](https://www.eclipse.org/projects/handbook/#resources-commit)):

Summary

<prefix_name>: Summary

The Subject shall describe what was changed in a single line max 72 characters long. It shall include a prefix for the module, component or feature which was changed e.g. “doc:” or “bazel:” It shall start with a capital letter and should not be ended by a trailing period in the subject line.

Good and bad examples for a subject are:

  • mw: Show colorful output not Add file

  • bazel: Test Requirement SWS_CM_00001 not Add test

  • osal: Split responsibilities of job handling and execution not Refactor code

Description

The description must contain a brief summary of the content of the commit and why this is necessary. Furthermore it must be consistent and logically complete.

If feasible, the commit message body should be extended with quoted material such as compiler warnings, debugger stack traces or measurement data for performance optimizations.

Layout Summary

In short the commit message shall consist of:

  • Summary

  • Empty line

  • Description

  • Empty line

  • Footer

Example

component: Short one line summary of change

More detailed explanatory text, if necessary. Wrap it to about 72
characters or less. The first line is treated as the subject 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);

-  Bullet points are okay, too
-  Typically a hyphen or asterisk is used for the bullet, followed by a
   space, using a hanging indent

Comment how the change was tested.

Notes about dependencies to other tools or commits in other
repositories.

Also-by: Some Bodyelse <somebodyelse@nowhere.com> |br|
Issue-Ref: <closes #xxx>, <fixes #xxy>, ...