Currently job artifacts in CI/CD pipelines on LRZ GitLab never expire. Starting from Wed 26.1.2022 the default expiration time will be 30 days (GitLab default). Currently existing artifacts in already completed jobs will not be affected by the change. The latest artifacts for all jobs in the latest successful pipelines will be kept. More information: https://gitlab.lrz.de/help/user/admin_area/settings/continuous_integration.html#default-artifacts-expiration

CONTRIBUTING.md 6.01 KB
Newer Older
Jens Petit's avatar
Jens Petit committed
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
# Contributing to elsa
This page summarizes advice how to contribute to elsa.

## General Workflow

#### a) Internal Developers
- Make a local clone of the elsa repository
- Checkout a new branch and work on your new feature or bugfix
- Push your branch and create a merge request targeting master

#### b) External Contributors
- Fork the elsa git repository
- Make a local clone your own fork
- Checkout a new branch and work on your new feature or bugfix
- Push your branch and send us a merge request targeting master

A branch should be short-lived and specific for a feature or bugfix. Commits should be squashed
into relevant groups before merging into master. Use
```
git rebase -i ${commit_to_rebase_on}
```
to clean up the commit history.

If during the development of a feature, `master` received updates, a `git rebase` should be preferred
over a `git merge` except when the changes are specifically needed in the feature branch:
```
git checkout feature-branch-name
git rebase master
```

Commit messages should follow some guidelines (derived from [this
blogpost](https://chris.beams.io/posts/git-commit/)):

- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Use the imperative mood in the subject line
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how

David Frank's avatar
David Frank committed
40
41
42
43
44
45
46
47
## Dependency Management

As of December 2020, we switched to [CPM](https://github.com/TheLartians/CPM.cmake) for our dependency management.
Hopefully, you don't really have to know and it doesn't get the way. See the [root CMakeLists.txt file](./CMakeLists.txt),
as an example for our usage.

It is recommended to set `CPM_SOURCE_CACHE` (see [here](https://github.com/TheLartians/CPM.cmake#cpm_source_cache) for
more info). It's an environment variable, that will save all dependencies outside of the build directory and -
48
for all projects using CPM - only one version of the dependency. This way no re-downloading is necessary.
David Frank's avatar
David Frank committed
49
Set it in your e.g. `.bashrc`.
50

Jens Petit's avatar
Jens Petit committed
51
52
53
54
## Testing
You can run the elsa unit tests by running `ctest` in the build folder. To specify which tests run,
filter with `ctest -R regular_expression`.

55
56
57
58
59
We use a testing style similar described in [Behaviour-Driven
Development](https://github.com/onqtam/doctest/blob/master/doc/markdown/testcases.md#bdd-style-test-cases) (BDD). Please
follow this style when adding new tests. However, isntead of using `SCENARIO` use `TEST_CASE` with the name of the
class under test at the beginning of the test name. Also be sure to add the tests to the test suite associated
to the module of the test.
60
61
62

We're currently relying on [doctest](https://github.com/onqtam/doctest/) as our testing framework, when
using assertion macros, please try to use the
63
[binary and unary asserts](https://github.com/onqtam/doctest/blob/master/doc/markdown/assertions.md#binary-and-unary-asserts)
64
65
as much as possible.

Jens Petit's avatar
Jens Petit committed
66
## Benchmarking
67

Jens Petit's avatar
Jens Petit committed
68
69
70
71
72
73
74
75
76
77
78
You can use the catch testing framework to do [benchmarking
](https://github.com/catchorg/Catch2/blob/master/docs/benchmarks.md). If so, add your benchmarking
case following this template
```cmake
if(ELSA_BENCHMARKS)
    ELSA_TEST(BenchmarkName)
endif()
```
which ensures that the test case is only registered and build if the cmake option was
enabled.

Jens Petit's avatar
Jens Petit committed
79
80
81
82
83
## Style Guide
We use the tool `clang-format` to autoformat our code with the [given style
file](.clang-format). Please make sure that your code is formatted accordingly, otherwise the CI
will fail in the first stage. You can either execute
```
84
85
86
find elsa/ -name '*.h' -or -name '*.hpp' -or -name '*.cpp' | xargs clang-format-10 -i -style=file $1
find examples/ -name '*.h' -or -name '*.hpp' -or -name '*.cpp' | xargs clang-format-10 -i -style=file $1
find benchmark/ -name '*.h' -or -name '*.hpp' -or -name '*.cpp' | xargs clang-format-10 -i -style=file $1
Jens Petit's avatar
Jens Petit committed
87
```
88
in the root folder, setup a git hook or integrate `clang-format` into your IDE. Note that we
89
currently use version 10.0.0, different versions might produce errors.
Jens Petit's avatar
Jens Petit committed
90
91
92
93
94

## Linting
We use `clang-tidy` with the enabled checks specified in [the configuration file](.clang-tidy). Note
that currently all `readability-*` checks have to pass, otherwise the CI will fail. We encourage
developers to check their code with `clang-tidy` and remove all warnings if applicable.
95
96

#### CMake
97
98
99
100
101
102
103
104

We use [cmakelang](https://cmake-format.readthedocs.io/en/latest/index.html) to enforce
certain style guide and reduce the changes of error in our CMake code, please check the guide to install it.

Currently, only the `cmake-lint` is used, but sooner rather than later, we'll also start
using `cmake-format` of the same package.

Please check the link above on how to install the package.
Jens Petit's avatar
Jens Petit committed
105
106
107
108
109
110
111
112
113
114
115
116

## Code Coverage
We use `lcov` with `gcov` for test coverage information. If you want to run this locally you have to
do a debug build with coverage option enabled
```
mkdir -p build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DELSA_COVERAGE=ON ../
make all -j4
make test_coverage
```
and then the results should be available at `build/test_coverage/index.html`. You can compare your
Jonas Jelten's avatar
Jonas Jelten committed
117
local results to [the latest master coverage results](https://ciip.in.tum.de/elsacoverage/).
118
119
120

## pre-commit

121
There is also a basic `.pre-commit-config.yaml` file to install pre-commit hooks using
122
[pre-commit](https://pre-commit.com/). You are highly encouraged to install the pre-commits
123
with `pre-commit install -t pre-commit -t commit-msg` such that they are run before each commit.
124
125
126

None of the commit hooks will change anything in your commit, they mearly check and error if
something is wrong.
127
128
129
130
131
132
133
134
135
136
137
138
139
140

## Building the Documentation
The [elsa documentation](https://ciip.in.tum.de/elsadocs/) is automatically built and deployed through the CI for each commit to master.
To build it locally the following packages are required: `sphinx doxygen` which should be available in
most major linux distributions or via pip. Additionally, the following sphinx extensions need to be installed via pip:
`sphinx-rtd-theme m2r2 breathe`.
Then simply build the documentation using ninja
```
mkdir -p build
cd build
cmake .. -GNinja
ninja docs
```
The docs should then be available at `build/docs/sphinx`.