Skip to content

Commit 34abb5c

Browse files
committed
Update documentation of CI checks
1 parent 449a357 commit 34abb5c

4 files changed

Lines changed: 46 additions & 25 deletions

File tree

‎docs/gettingstarted/contributingtocode.md‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -90,20 +90,24 @@ Pull requests are tested with automatic continuous-integration (CI) checks which
9090

9191
The CI checks evaluate:
9292

93+
- Compilation: Verifies that the code compiles without problems on all supported platforms.
94+
- Compilation warnings are not tolerated in PRs.
9395
- Code formatting
96+
- [include formatter](../tools/README.md#fixing-include-format) + [clang-format](https://clang.llvm.org/docs/ClangFormat.html) ("clang-format" check)
97+
- [Ruff formatter](https://docs.astral.sh/ruff/formatter/) (Python)
9498
- Code quality
95-
- [MegaLinter](https://megalinter.io/) (e.g. [cpplint](https://github.com/cpplint/cpplint), [Cppcheck](../tools/README.md#cppcheck))
99+
- [MegaLinter](https://megalinter.io/) (e.g. [cpplint](https://github.com/cpplint/cpplint), [Cppcheck](../tools/README.md#cppcheck), [Ruff linter](https://docs.astral.sh/ruff/linter/) (Python), [ShellCheck](https://www.shellcheck.net/) (Shell))
96100
- [O2 linter](../tools/o2linter.md)
97-
- [Clang-Tidy](../tools/README.md#clang-tidy)
98-
- Compilation: Verifies that the code compiles without problems on all supported platforms.
101+
- [Clang-Tidy](../tools/README.md#clang-tidy) ("[build/O2Physics/code-check](../tools/README.md#running-with-o2physics-code-check)" check)
99102
- PR properties
100-
- Labeler: Assigns [labels](https://github.com/AliceO2Group/O2Physics/labels) to the PR based on which parts of the code base were modified.
103+
- Labeler: Assigns [labels](https://github.com/AliceO2Group/O2Physics/labels) to the PR based on which parts of the repository were modified.
101104
- Title prefix checker: Verifies that the title of the PR has a valid prefix with tags corresponding to the labels. If a valid prefix is not found, it is created.
102105

103-
- __Policy when dealing with linter / code-checker__
104-
- It is agreed that the issues brought up by linter and code-checker tools should be fixed on a best-effort basis.
105-
- However, for the purposes of merging, the linter checks are not mandatory.
106-
- The final decision on merging PRs is taken by the code owners.
106+
__Policy when dealing with code analysis checks__
107+
108+
- It is agreed that the issues brought up by code analysis tools (linters) should be fixed on a best-effort basis.
109+
- However, for the purposes of merging, the linter checks are not mandatory.
110+
- The final decision on merging PRs is taken by the code owners.
107111

108112
Checks flagged as "Required" must succeed before a PR can be merged.
109113

@@ -112,7 +116,7 @@ PRs from first-time contributors (who have not authored any commit in the reposi
112116

113117
If a check fails, you can click on the name of the check to see more information about the errors in the log of the test.
114118

115-
If the clang-format check (or a formatting linter in MegaLinter) fails, an automatic PR with the formatting fixes is opened in your fork and a notification email is sent to you.
119+
If the clang-format check (or a formatter in MegaLinter) fails, an automatic PR with the formatting fixes is opened in your fork and a notification email is sent to you.
116120
You have to merge this formatting PR to update your branch (and your opened PR).
117121

118122
```tip

‎docs/gettingstarted/installing.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -336,6 +336,10 @@ This requires that you have successfully built Git branch `[branch]` (e.g. `mast
336336
You also need to have `direnv` installed and hooked (see [instructions](https://direnv.net/docs/installation.html)) to load the correct build environment automatically when you enter the build directory (and to unload it when you exit).
337337
```
338338
339+
```tip
340+
This works also if you are developing in a different Git branch and you just want to compile changes on top of the full build of the `master` branch.
341+
```
342+
339343
```warning
340344
This only builds O2Physics. If you have updated O2 or alidist, you first need to do a full build with aliBuild.
341345
```

‎docs/tools/README.md‎

Lines changed: 23 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -33,20 +33,21 @@ See the dedicated [O2 linter](o2linter.md) page.
3333
Pre-commit hooks run when you execute `git commit` and are used to validate the staged changes that are about to be committed.
3434
If any hook fails, the commit is not made.
3535

36-
In the O2Physics repository, pre-commit hooks are [configured](https://github.com/AliceO2Group/O2Physics/blob/master/.pre-commit-config.yaml) to format C++ code with [clang-format](https://clang.llvm.org/docs/ClangFormat.html) and lint it (check for issues) with [cpplint](https://github.com/cpplint/cpplint).
37-
This way you can make sure that your changes will pass the C++ formatting check and the cpplint check in [MegaLinter](https://megalinter.io/) when you make your pull request.
36+
In the O2Physics repository, pre-commit hooks are [configured](https://github.com/AliceO2Group/O2Physics/blob/master/.pre-commit-config.yaml) to detect invalid files and to format and check code using some of the tools included in the [automatic CI checks](../gettingstarted/contributingtocode.md#automatic-checks).
37+
This way you can make sure that your changes will pass the same checks on GitHub when you make your pull request.
3838

3939
### How to use pre-commit hooks
4040

41-
1. [Install pre-commit](https://pre-commit.com/#installation) (typically `pip install pre-commit`).
41+
1. [Install pre-commit](https://pre-commit.com/#installation) (typically `pip install pre-commit` or `pipx install pre-commit`).
4242
1. Enter the `O2Physics` directory.
4343
1. [Install the Git hook scripts](https://pre-commit.com/#3-install-the-git-hook-scripts): `pre-commit install`.
4444

4545
Next time you execute `git commit`, the hooks will run automatically.
4646

47-
- If the clang-format hook fails, it means your staged files have been formatted.
48-
- If the cpplint hook fails, the linter has found issues that need to be fixed.
49-
- Updated files need to be staged with `git add` before attempting `git commit` again.
47+
- If a formatting hook fails, it means your staged files have been formatted.
48+
- If a linter hook fails, the linter has found issues that should be fixed.
49+
- Updated files need to be staged with `git add` in order to include the changes in the next attempt to commit them.
50+
- If needed, the pre-commit hooks can be skipped entirely with `git commit -n` or selectively (see the [documentation](https://pre-commit.com/#temporarily-disabling-hooks)).
5051

5152
## [Clang-Tidy](https://clang.llvm.org/extra/clang-tidy/)
5253

@@ -67,6 +68,10 @@ Without further options, you can run Clang-Tidy with
6768
clang-tidy file1 file2 ...
6869
```
6970

71+
```tip
72+
This is the best option when you are developing in a different Git branch and you just [compile changes](../gettingstarted/installing.md#building-partially-for-development-using-ninja) on top of the full build of the `master` branch.
73+
```
74+
7075
### Running with O2Physics-code-check
7176

7277
Clang-Tidy runs on O2Physics PRs as the O2Physics-code-check tool under the `build/O2Physics/code-check` CI check, using the repository configuration.
@@ -76,16 +81,20 @@ You can run the check locally to test C++ files modified since `<base-commit>` u
7681
aliBuild build O2Physics-code-check -e ALIBUILD_BASE_HASH=<base-commit> -e ALIBUILD_HEAD_HASH=<head-commit>
7782
```
7883

79-
where `<base-commit>` is typically `master` and `<head-commit>` is `HEAD` by default if `ALIBUILD_HEAD_HASH` is omitted.
84+
where `<base-commit>` is typically `upstream/master` and `<head-commit>` is `HEAD` by default if `ALIBUILD_HEAD_HASH` is omitted.
8085
If `ALIBUILD_BASE_HASH` is omitted, all tracked C++ files are analysed.
8186

82-
Enabled checks can be modified with the `O2PHYSICS_CHECKER_CHECKS=...` option.
87+
Enabled checks can be modified with the `-e O2PHYSICS_CHECKER_CHECKS=...` option.
8388

84-
Fixes can be enabled with the `O2PHYSICS_CHECKER_FIX=1` option.
89+
Fixes can be enabled with the `-e O2PHYSICS_CHECKER_FIX=1` option.
90+
91+
```warning
92+
Running O2Physics-code-check involves building O2Physics which might mean a full build of the current branch in case you have not done it yet.
93+
```
8594

8695
### Checking naming conventions
8796

88-
The [`readability-identifier-naming`](https://clang.llvm.org/extra/clang-tidy/checks/readability/identifier-naming.html) check can fix deviations from the [naming conventions](https://rawgit.com/AliceO2Group/CodingGuidelines/master/naming_formatting.html).
97+
The [`readability-identifier-naming`](https://clang.llvm.org/extra/clang-tidy/checks/readability/identifier-naming.html) check can fix deviations from the [naming conventions](https://aliceo2group.github.io/CodingGuidelines/naming_formatting.html).
8998

9099
```tip
91100
Learn how to form a [correct camelCase name](https://google.github.io/styleguide/javaguide.html#s5.3-camel-case).
@@ -125,16 +134,16 @@ Headers from the same project should be included using quotation marks (`#includ
125134
Failing to do so points the preprocessor to a [wrong location](https://gcc.gnu.org/onlinedocs/cpp/Include-Syntax.html) and can result in picking a wrong header.
126135
See also the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#sf12-prefer-the-quoted-form-of-include-for-files-relative-to-the-including-file-and-the-angle-bracket-form-everywhere-else).
127136

128-
The [`format_includes.awk`](https://github.com/AliceO2Group/O2Physics/blob/master/Scripts/format_includes.awk) script allows to fix the include format in a provided O2Physics file.
137+
The [`format_includes.py`](https://github.com/AliceO2Group/O2Physics/blob/master/Scripts/format_includes.py) script allows to fix the include format in provided O2Physics files.
129138

130-
To fix the include format in all `.h`, `.cxx` files in O2Physics, execute:
139+
To fix the include format in files in O2Physics, execute:
131140

132141
```bash
133-
find . -name "*.h" -o -name "*.cxx" | parallel "awk -f Scripts/format_includes.awk \"{}\" > \"{}.tmp\" && mv \"{}.tmp\" \"{}\""
142+
Scripts/format_includes.py file1 file2 ...
134143
```
135144

136145
```note
137-
The include format is corrected automatically in O2Physics PRs as part of the automatic formatting PR created by the [clang-format CI check](../gettingstarted/contributingtocode.md#automatic-checks).
146+
The include format is corrected automatically in O2Physics PRs as part of the automatic formatting PR created by the [clang-format CI check](../gettingstarted/contributingtocode.md#automatic-checks). You can also run the script automatically as a [pre-commit hook](#pre-commit-hooks).
138147
```
139148

140149
## [Cppcheck](https://cppcheck.sourceforge.io/)

‎docs/tools/o2linter.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,14 @@ The [`o2_linter.py`](https://github.com/AliceO2Group/O2Physics/blob/master/Scrip
2828
You can execute the script locally from the O2Physics directory with:
2929

3030
```bash
31-
python3 Scripts/o2_linter.py <files>
31+
Scripts/o2_linter.py file1 file2 ...
3232
```
3333

34-
Example: `python3 Scripts/o2_linter.py $(find . -path ./.git -prune -o -type f)` to lint all O2Physics files.
34+
Example: `Scripts/o2_linter.py $(find . -path ./.git -prune -o -type f)` to lint all O2Physics files.
35+
36+
### As a pre-commit hook
37+
38+
If you enable pre-commit hooks in your local repository, O2 linter will check your staged files before each commit. See [the instructions](README.md#pre-commit-hooks).
3539

3640
### In Visual Studio Code
3741

0 commit comments

Comments
 (0)