fdo-mirrors/NetworkManager
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/NetworkManager/NetworkManager.git synced 2025-12-23 23:40:07 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

CONTRIBUTING: explain which version of clang-format to use

Browse source
This commit is contained in:
Thomas Haller 2021-08-26 14:02:56 +02:00
parent 101a7cb56d
commit 727bea99b6
No known key found for this signature in database
GPG key ID: 29C2366E4DFC5728
1 changed files with 38 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
CONTRIBUTING.md
View file

@ -33,14 +33,22 @@ new contributions already must already agree to that.
For more details see [RELICENSE.md](RELICENSE.md). For more details see [RELICENSE.md](RELICENSE.md).
Coding Standard Coding Style
--------------- ------------
### clang-format
The formatting is automated using clang-format. Run `./contrib/scripts/nm-code-format.sh -i`
([[1]](contrib/scripts/nm-code-format.sh)) to reformat the code or run `clang-format` yourself.
You may also call `./contrib/scripts/nm-code-format-container.sh` which runs a
Fedora container using podman.
As the generated format depends on the version of clang-format, you need to use the
correct clang-format version. That is basically the version that our [gitlab-ci
pipeline](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/pipelines) uses
for the "check-tree" test. This is the version from a recent Fedora installation.
The formatting uses clang-format with clang 11.0. Run
`./contrib/scripts/nm-code-format.sh -i` to reformat the code
or call `clang-format` yourself.
You may also call `./contrib/scripts/nm-code-format-container.sh`
which runs a Fedora 33 container using podman.
You are welcome to not bother and open a merge request with You are welcome to not bother and open a merge request with
wrong formatting, but note that we then will automatically adjust wrong formatting, but note that we then will automatically adjust
your contribution before merging. your contribution before merging.
@ -53,6 +61,8 @@ the reformatting commit with git-blame:
$ git config --add 'blame.ignoreRevsFile' '.git-blame-ignore-revs' $ git config --add 'blame.ignoreRevsFile' '.git-blame-ignore-revs'
``` ```
### Style
Since our coding style is entirely automated, the following are just Since our coding style is entirely automated, the following are just
some details of the style we use: some details of the style we use:
@ -70,6 +80,9 @@ some details of the style we use:
- GOOD: `MyObject *object;` - GOOD: `MyObject *object;`
- BAD: `MyObject *object = complex_and_long_init_function(arg1, arg2, arg3);` - BAD: `MyObject *object = complex_and_long_init_function(arg1, arg2, arg3);`
* Declare each variable on a separate line:
- BAD: `int i, j;`
* 80-cols is a guideline, don't make the code uncomfortable in order to fit in * 80-cols is a guideline, don't make the code uncomfortable in order to fit in
less than 80 cols. less than 80 cols.
@ -77,6 +90,22 @@ some details of the style we use:
- GOOD: `#define MY_CONSTANT 42` - GOOD: `#define MY_CONSTANT 42`
- BAD: `static const unsigned myConstant = 42;` - BAD: `static const unsigned myConstant = 42;`
Additionally, we require to build without compiler warnings for the warnings
that we enable. Also, our language is C11 with some GCC-isms (like typeof(),
expression statements, cleanup attribute). In practice, we support various versions
of GCC and clang. The supported C "dialect", the compilers and
libc are the one that we can practically build and test in our CI. We don't
target a theoretical, pure C standard or a libc/compiler that we don't test.
Patches for making NetworkManager more portable are welcome, if there is a
practical use and CI tests.
### Checkpatch
We have a [checkpatch.pl](contrib/scripts/checkpatch.pl) script, which is
also run in our gitlab-ci. Review the warnings, but as these are just heuristics,
there might be valid reasons to reject them. There is also a
[git hook](contrib/scripts/checkpatch-git-post-commit-hook) which you can call
from `.git/hooks/post-commit`.
Unit Tests Unit Tests
---------- ----------
@ -90,7 +119,7 @@ files. The unit test fail in that case, to indicate that the generated
files no longer match what is commited to git. files no longer match what is commited to git.
You can also automatically regenerate the files by running `NM_TEST_REGENERATE=1 make check`. You can also automatically regenerate the files by running `NM_TEST_REGENERATE=1 make check`.
Note that test-client requires working translation. Note that test-client requires working translation.
See the [comment](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/blob/eee4332e8facfa5ff5940fa1655575d76ca143ea/src/tests/client/test-client.py#L19) See the [comment](https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/blob/main/src/tests/client/test-client.py#L14)
for how to configure it. for how to configure it.
@ -261,7 +290,7 @@ We use GObjects and GObject Properties in various cases. For example:
properties. In that case, avoid adding a getter too, the property only needs to be properties. In that case, avoid adding a getter too, the property only needs to be
writable and you should access it via the C wrapper. writable and you should access it via the C wrapper.
In general, use GObject sparsely and avoid them (unless you need them for one of the In general, use GObject properties sparsely and avoid them (unless you need them for one of the
reasons above). reasons above).
Almost always add a `#define` for the property name, and use for example Almost always add a `#define` for the property name, and use for example