Contributing¶
Contributions are highly welcome. Here is some information getting you started.
NeoFOAM Code Style Guide¶
To simplify coding and code reviews you should adhere to the following code style. However, most of NeoFOAMs code style guide is checked via automated tools. For example, formatting and non-format related code style is enforced via clang-format and clang-tidy. Corresponding configuration files are .clang-format and .clang-tidy. Furthermore, adequate licensing of the source code is checked via the reuse linter and typos checks for obvious spelling issues. Thus, this style guide doesn’t list all stylistic rules explicitly but rather gives advice for ambiguous situations and mentions the rational for some decisions.
We generally try to comply with the C++ core guidelines.
Use camelCase for functions and members and capitalized CamelCase for classes
Use descriptive template parameter names. For example, prefer
template <class ValueType>
overtemplate <class T>
if the type can be a float or double.Use
[[nodiscard]]
except for getters. To indicate that a function simply returns a value instead of performing expensive computations,[[nodiscard]]
can be omitted.Use
final
except for abstract classes. NeoFOAMs aims at having a rather flat inheritance hierarchy and composition is generally preferred. To avoid unintended inheritance, using final is advised.Avoid storing references as data members in classes. An exception might be a
const Unstructured& mesh
as it will most likely outlive any other objects.Private member variables should be suffixed with
_
.Order of parameters to functions should be in, in-out, out. E.g.
foo(const Type& in, Type& inOut, Type& out)
instead offoo(Type& inOut, Type& out, const Type& in)
or some other variation.Use US spelling
Folder structure and file names:
Use camelCase for files and folder names
The location of implementation and header files should be consistent. i.e. a file
src/model/a.cpp
should have a header file ininclude/NeoFOAM/model/a.hpp
and the corresponding test implementation intest/model/a.cpp
File and folder names should not be redundant. Ie.
finiteVolume/cellCentred/geometryModel/finiteVolumecellCentredgeometryModel.hpp
should befiniteVolume/cellCentred/geometryModel/model.hpp
.
Collaboration via Pull Requests¶
If you want to contribute a specific feature or fix, please don’t hesitate to open a PR. After creating the PR, the following process is applied.
Request a review by a given person or set the Ready-for-Review label.
At least one (ideally two) approval(s) is/are required before a PR can be merged.
Make sure that all required pipelines succeed.
If you add new features, make sure to provide sufficient unit tests. Also at some point before merging you can add the
full-ci
label to include build and tests on GPU hardware.If you add a new feature or bug-fix, please add an entry to the
Changelog.md
file. For pure refactor PRs, theSkip-Changelog
label can be set.If the PR should be merged in a specific order or if you don’t have the permission to merge, add the
ready-to-merge
label.Before merging, make sure to rebase your PR on to the latest state of
main
.Make sure to add yourself to the
Authors.md
file.To simplify the review process, small to medium sized PRs are preferred. If your PR exceeds 1000 lines of code changes, consider to break the PR up into smaller PRs which can be merged via stacked PRs.
Github Workflows and Labels¶
In order to influence the workflow pipeline and to structure the review process, several labels exist. The following labels and their meaning are discussed here:
ready-for-review
: Signal that the PR is ready for review.
ready-to-merge
: Signal that the work on this PR has been finished and can be merged.
Skip-Changelog
: Don’t check whether the changelog has been updated. Use this label if the changes are not any new features or bug-fixes.
Skip-build
: Don’t run any build steps, including building the compile commands database.
Skip-cache
: Don’t cache the build folders. Forces to rebuild the build folder after every push to GitHub.
full-ci
: Run tests on AWS.
A full list of the labels can be found here.
Building the Documentation¶
NeoFOAM’s documentation can be found main and doxygen documentation can be found online. However, if you want to build the documentation locally, you can do so by executing the following steps. First, make sure that Sphinx and Doxygen are installed on your system. Second, execute the following commands:
cmake -B build -DNEOFOAM_BUILD_DOC=ON # configure the build cmake --build build --target sphinx # build the documentation # or sphinx-build -b html ./doc ./docs_build
The documentation will be built in the docs_build
directory and can be viewed by opening the index.html
file in a web browser.
firefox docs_build/index.html
Alternatively, the documentation can be built by just adding the -DNEOFOAM_BUILD_DOC=ON
to the configuration step of the build process and then building the documentation using the sphinx
target.