A commit groups file changes with a title and description of the changes and additional metadata like change date, author, and committer.
These Commit Message Guidelines define and describe how changes shall be structured and described in commits. Most notably, the text form in which to title the changes.
-
Each change goes into its own commit. If you want to summarize what you did with this commit (in the commit message) and you start using the word "and", you probably want to split the commit up into 2 or more individual commits.
-
Each commit should compile (try to make each commit self-contained so that it is possible to compile the code at each commit).
-
Take your time when composing the commit message. In order to have a good git-history the commit messages are essential. Also if you put effort into the commit-message, you'll save work when creating a PullRequest as the description is already available.
Commit messages must follow this scheme:
TYPE(Scope): Summary
Message Body
Footer
The blank lines in between are mandatory. A commit must include a TYPE and a Summary and may
additionally contain any of the other components listed here.
The first line ("Subject line") should not exceed 50-70 characters. This is what gets displayed on GitHub at first glance, so it
should contain the most important information. In order for it to be as short and precise as possible, there is the TYPE and
optionally a Scope. With these it should already be clear what this commit is about in general. The short Summary should
then include further information that is important to understand the general idea of this commit at a glance.
The TYPE is one of the following:
| TYPE | Description | Example |
|---|---|---|
| BREAK | A breaking change - not backwards-compatible | A change in protocol (e.g. change UDP message format) |
| FEAT | Introduction of a new feature (or extension of an existing one) | |
| FIX | A bug fix | |
| FORMAT | Change of formatting - does not influence how the code works | Change indentation of a line; Add braces around if body |
| DOCS | Changes to the documentation (either in-source or out-of-source) | Add a Doxygen comment to a function |
| TEST | Adds, changes or removes a test-case | |
| MAINT | Maintenance - Change of non-code files | Make changes to .plist or .rc files |
| CI | Changed something for the CI (continuous integration) | Update TravisCI to use newer ubuntu version |
| REFAC | Code refactoring | Rename variable x to y |
| BUILD | Changes related to the build process / buildsystem | Fix cmake script |
| TRANSLATION | Translation updates and changes | Update translation files |
| CHANGE | Something was changed without falling into existing categories | Changed the default of a setting |
| REVERT | A previous commit had to be reverted because e.g. it was buggy | - |
The TYPE has to be in all-uppercase in order for it to stand out.
If you feel like you need to use 2 or more types for a single commit but can't split it into multiple commits, you can
combine types with /: FEAT/CI: <Summary>
What area is the change about. For now we don't have fixed scope keywords. A scope could be something like ui, client,
server, ice, ...
The Summary is the heart of the subject line. It should contain a very brief summary of what you did in that commit.
In order to make this as short as possible, you may use grammatically incorrect sentences
("Add ability" instead of "add the ability").
In general the Summary should answer the question "Applying this commit will ..." where "..." is your Summary.
If your Summary contains "and", you should probably split your commit up.
Note: Issue references (such as #2305) must not be used in the Summary!
Here you give more details about the commit. Why is it necessary and what are the details of the change. You can use multiple paragraphs for this and be as verbose as you want.
The Message Body should reference issues that are related to this change, but also provide a short summary of what that
issue is about (so that it can be understood without having to open that issue).
The Message Body should contain enough information for someone to be able to look at this commit at some point in the
future and know exactly what it does and why it was needed.
The Footer contains a list of issue references prefixed by a keyword like Closes, Fixes or Implements.
Each reference should be on its own line:
Implements #1234
Closes #2215
Additionally the Footer may contain another paragraph indicating that a given commit was co-authored by other people.
Each co-author should be listed in a new line like so:
Co-Authored-By: Author name <[email protected]>
Co-Authored-By: Other author <[email protected]>
We have used the term "reference" a few times in these guidelines. A reference has the form #<ID> where <ID> is the
ID GitHub assigns to the respective issue or PullRequest (it's the number that is displayed next to the title). You'll
notice that these references are actually turned into a link when viewing the commit message on GitHub. This is done
automatically by GitHub. You don't have to use a link in your commit message. In fact you should not use a link for
this purpose as this is just unnecessarily verbose and makes it hard to read the commit message outside of GitHub.
FEAT(client): Add possibility to change username
Co-Authored-by: Gina Taylor <[email protected]>
FEAT(client): Add possibility to change username
As requested in #1234 this commit implements the ability to change your
username while being connected to a server.
For that X and Y had to be implemented.
The change now works by sending a XYZ message to the server with the "foo"
and "bar" fields set.
Implements #1234
FIX(client): Crash when loading settings
MAINT: Add XY to README
This guide was inspired by https://github.com/bluejava/git-commit-guide