# Contribution Guide

[[_TOC_]]

## General Remarks

A common guideline for source code makes it much easier to understand code
written by other colleagues. In general we adopt the code style guidelines
defined by the OpenFOAM Foundation

* <https://openfoam.org/dev/how-to-contribute>
* <https://openfoam.org/dev/coding-style-guide>
* <https://openfoam.org/dev/code-quality>

## Git Configuration

The source code is managed using the Git version control system. Git allows
you to track changes to files, collaborate on projects, and manage different
versions of the code. Make sure to configure Git with your name and email
address before making any commits.

```shell
git config --global user.email "jane.doe@company.de"
git config --global user.name "Jan Doe"
```

It is recommended to add a digital signature to your commits, as it provides
extra assurance that a commit actually originated from you. [^2].

## Static Code Analysis (Linting)

Make sure that source code and dictionary files contain a valid header:

* for C++ source code: `etc/codeTemplates/app/app.C`
* for dictionaries: `etc/controlDict`
* for Bash: `etc/codeTemplates/script/bash.sh`
* for Python: `etc/codeTemplates/script/python.py`
* for Snakemake: `etc/codeTemplates/script/Snakemake`

Mark the changes in copies of the original release files with code repository
comments according to `etc/codeTemplates/addonCommentStyles`.

### Linting Code Style

The repository is equipped with a configuration file for pre-commit[^7]. To run
the checks install pre-commit[^7] and activate the git hooks

```shell
pre-commit install
```

Spellchecking is done with `codespell`. Add words that should be ignored to
`.gitlab/config/ignore_words.txt`.

If you are implementing a new model from the literature, make sure to cite it
appropriately in the header file by using the APA style, following the
OpenFOAM Foundation code style guidelines[^1].

## Integrated development environment (Visual Studio Code)

Visual Studio Code[^4] is recommended for both development and general
usage. It comes with an integrated terminal and allows syntax highlighting.

### Setup of Visual Studio Code

1. Install VS Code[^6].
2. To avoid warnings when working on large file systems with VS Code, allow
your local system to watch more files than usual: Open `/etc/sysctl.conf` with
root privileges and add the line `fs.inotify.max_user_watches = 524288`. Apply
these changes with `sudo sysctl -p`.

### Usage of Visual Studio Code

Visual Studio Code (VS Code) settings are provided in a folder named `.vscode/`,
which has to be placed in the working directory.

1. Copy the folder containing the suggested settings to the directory you want
   to open, for example:

   ```bash
   cp -r etc/vscode/ .vscode/
   ```

2. Open the target folder with VS Code. VS Code detects the `.vscode/` folder
   and the settings are loaded.

   If not already done, VS Code asks you to install the recommended extensions
   (defined in `.vscode/extensions.json`).

   **Docker users**:
   * Start your container as usual. Hit `F1` and `Attach to running container`.
     Open the folder `$WM_PROJECT_SITE/$WM_PROJECT_VERSION` with VS Code.
     VS Code detects the `.vscode` folder which was copied in step 1.

### Useful shortcuts for Visual Studio Code

Make sure to provide the VS Code setting files first (described below).

| shortcut       | action                                            |
|----------------|---------------------------------------------------|
| `Ctrl+Shift+B` | build source code (executes `./Allwmake -j`)      |
| `Ctrl+Click`   | go to file/definition                             |
| `Ctrl+P`       | search for specific files to edit them            |
| `Alt+O`        | switch between header and source file             |
| `F1`           | access actions like `Attach to running container` |

### GitLab Workflow with Visual Studio Code

The extension `GitLab Workflow`[^5] provides a large number of GitLab features.
It is already added to the settings suggested above. You have to create and
paste a personal access token (PAT) with `api` and `read_user` permissions.
Afterwards add the following environment variables to your shell:

```bash
export GITLAB_WORKFLOW_INSTANCE_URL="https://codebase.helmholtz.cloud"
export GITLAB_WORKFLOW_TOKEN="PASTE YOUR TOKEN HERE"
```

**Docker users**: Make sure that these variables are also known within the
container.

### Notes on some specific settings for Visual Studio Code

* To make problem matching work, absolute paths are used for compilation:
`Ctoo_VSCode` in `tasks.json` overwrites `Ctoo` defined in `/wmake/rules/*/c++`
* Red zigzag underlines are buggy and therefore disabled:
`"C_Cpp.errorSquiggles": "Disabled"` in `settings.json`

## Unit and Integration Tests

Supply tests for important features in `testAddon` or `testCuda`. A test should:

* run in a few seconds on one core (2 cores for parallel features)
* include an `Allrun` script (template in `etc/template/case`)
* be restricted to utilities and solvers included in software released by the
  OpenFOAM Foundation
* not contain pre- or postprocessing
* contain a `validation` sub-directory for reference data
* contain a `README.md` for documentation
* use `foamPostProcess -func "deviation(field=U, reference=U.ref)"` to check
  against a known numerical or analytical solution

In case the solver or the application writes tabs in output files required for
validation use `sed -i 's/\t/ /g' <file>` to replace tabs by a space and
`diff -b` to ignore differences in the amount of white space. The command
`column -t <file>` can be used to format pretty tables.

Tests in `test` directory are copies of tests in the release and should be
identical.

## Demonstration Tutorials

Supply tutorials for every major development or complex set-up in
`tutorialsAddon` or `tutorialsCuda`. A tutorial should:

* guide users through the features and possibilities of your developments
* run on a maximum of two cores (preferably one)
* include an `Allrun` script (see `etc/template/case` for an example)
* contain a sub-directory called `validation` for reference and additional data

For pre- and postprocessing in tutorials:

* use gnuplot and/or python3
* generate graphs by `( cd validation && ./createGraphs )`
* a template for createGraphs can be found in `etc/codeTemplates/script`
* if available use CSV format with space separator (allows to select column by
  name in gnuplot: `u 1:(column("alpha.air"))`)

Tutorials in `tutorials` directory are copies of tutorials in the release and
should be identical.

---
[^1]: <https://openfoam.org/dev/coding-style-guide/#sec-2-7>
[^2]: <https://docs.gitlab.com/user/project/repository/signed_commits/>
[^4]: <https://code.visualstudio.com/docs>
[^5]: <https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow>
[^6]: <https://code.visualstudio.com/docs/setup/setup-overview>
[^7]: <https://pre-commit.com>
