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
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
# Coding style
- Indentation in tabs, 8 characters wide, spaces after the tabs where
vertical alignment is required (see below)
**Note: this file uses spaces due to markdown rendering issues for tabs.
Code must be implemented using tabs.**
- Max line width 80ch, do not break up printed strings though
- Break up long lines at logical groupings, one line for each logical group
```c
int a = somelongname() +
someotherlongname();
if (a < 0 &&
(b > 20 & d < 10) &&
d != 0.0)
somelongfunctioncall(arg1,
arg2,
arg3);
```
- Function declarations: return type on separate line, {} on separate line,
arguments broken up as above.
```c
static inline int
foobar(int a, int b)
{
}
void
somenamethatiswaytoolong(int a,
int b,
int c)
{
}
```
- `/* comments only */`, no `// comments`
- `variable_name`, not `VariableName` or `variableName`. same for functions.
- no typedefs of structs, enums, unions
- if it generates a compiler warning, it needs to be fixed
- if it generates a static checker warning, it needs to be fixed or
commented
- declare variables at the top, try to keep them as local as possible.
Exception: if the same variable is re-used in multiple blocks, declare it
at the top.
Exception: basic loop variables, e.g. for (int i = 0; ...)
```c
int a;
int c;
if (foo) {
int b;
c = get_value();
usevalue(c);
}
if (bar) {
c = get_value();
useit(c);
}
```
- do not mix function invocations and variable definitions.
wrong:
```c
{
int a = foo();
int b = 7;
}
```
right:
```c
{
int a;
int b = 7;
a = foo();
}
```
There are exceptions here, e.g. `tp_libinput_context()`,
`litest_current_device()`
- if/else: { on the same line, no curly braces if both blocks are a single
statement. If either if or else block are multiple statements, both must
have curly braces.
```c
if (foo) {
blah();
bar();
} else {
a = 10;
}
```
- public functions MUST be doxygen-commented, use doxygen's `@foo` rather than
`\foo` notation
- `#include "config.h"` comes first, followed by system headers, followed by
external library headers, followed by internal headers.
sort alphabetically where it makes sense (specifically system headers)
```c
#include "config.h"
#include <stdio.h>
#include <string.h>
#include <libevdev/libevdev.h>
#include "libinput-private.h"
```
- goto jumps only to the end of the function, and only for good reasons
(usually cleanup). goto never jumps backwards
- Use stdbool.h's bool for booleans within the library (instead of `int`).
Exception: the public API uses int, not bool.
# Git commit message requirements
Our CI will check the commit messages for a few requirements. Below is the
list of what we expect from a git commit.
## Commit message content
A [good commit message](http://who-t.blogspot.com/2009/12/on-commit-messages.html) needs to
answer three questions:
- Why is it necessary? It may fix a bug, it may add a feature, it may
improve performance, reliabilty, stability, or just be a change for the
sake of correctness.
- How does it address the issue? For short obvious patches this part can be
omitted, but it should be a high level description of what the approach
was.
- What effects does the patch have? (In addition to the obvious ones, this
may include benchmarks, side effects, etc.)
These three questions establish the context for the actual code changes, put
reviewers and others into the frame of mind to look at the diff and check if
the approach chosen was correct. A good commit message also helps
maintainers to decide if a given patch is suitable for stable branches or
inclusion in a distribution.
## Developer Certificate of Origin
Your commit **must** be signed off with a line:
```
Signed-off-by: <your name> <your email address>
```
By signing off, you indicate the [developer certificate of origin](https://developercertificate.org/).
> By making a contribution to this project, I certify that:
>
> (a) The contribution was created in whole or in part by me and I
> have the right to submit it under the open source license
> indicated in the file; or
>
> (b) The contribution is based upon previous work that, to the best
> of my knowledge, is covered under an appropriate open source
> license and I have the right under that license to submit that
> work with modifications, whether created in whole or in part
> by me, under the same open source license (unless I am
> permitted to submit under a different license), as indicated
> in the file; or
>
> (c) The contribution was provided directly to me by some other
> person who certified (a), (b) or (c) and I have not modified
> it.
>
> (d) I understand and agree that this project and the contribution
> are public and that a record of the contribution (including all
> personal information I submit with it, including my sign-off) is
> maintained indefinitely and may be redistributed consistent with
> this project or the open source license(s) involved.
## Commit message format
The canonical git commit message format is:
```
one line as the subject line with a high-level note
full explanation of the patch follows after an empty line. This explanation
can be multiple paragraphs and is largely free-form. Markdown is not
supported.
You can include extra data where required like:
- benchmark one says 10s
- benchmark two says 12s
Signed-off-by: <your name> <your email>
```
The subject line is the first thing everyone sees about this commit, so make
sure it's on point.
## Commit message technical requirements
- The commit message should use present tense (not past tense). Do write
"change foo to bar", not "changed foo to bar".
- The text width of the commit should be 78 chars or less, especially the
subject line.
- The author and signed-off-by must be your real name and email address. We
do not accept the default `@users.noreply` gitlab addresses.
```
git config --global user.name Your Name
git config --global user.email your@email
```
|
