1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
# General philosophy
- **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 message
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.
## Subject line
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.
### TYPE
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 | Change of the README |
| CI | Changed something for the CI (continous integration) | Update TravisCI to use newer ubuntu version |
| REFAC | Code refactoring | Renamed variable `x` to `y` |
| BUILD | Changes related to the build process / buildsystem | Fixed cmake script |
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>`
### Scope
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`, `grpc`, ...
### Summary
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`!
## Message Body
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.
## Footer
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 <author@example.com>
Co-Authored-By: Other author <other@example.com>
```
## References
We have used 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.
## Examples
```
FEAT(client): Add possibility to change username
Co-Authored-by: Gina Taylor <g.taylor@myspace.com>
```
```
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
|