How to Contribute

Table of Contents

Forking the repository
Making Changes and Pushing to the Repository
Testing
How to Work with CMake Presets
Code Formatting
How to use clang-tidy to check your code
Installing Pre-commit Hooks
Useful GIT commands

Forking the repository

Before making any changes, you need to fork the repository to your own GitHub account. You can do this by clicking the Fork button at the top right corner of the repository page on GitHub. Once forked, clone your forked repository to your local machine:

git clone https://github.com/your-username/MeltPoolDG-dev.git

Then, navigate into the repository directory:

cd MeltPoolDG-dev

Add the original repository as an upstream remote to stay updated with changes:

git remote add upstream https://github.com/MeltPoolDG/MeltPoolDG-dev.git

Now, you are ready to start contributing!

Making Changes and Pushing to the Repository

Get the Latest `master` Branch

Before making changes, ensure your local branch is up to date with the original repository (see Useful GIT commands section):

git fetch upstream
git rebase upstream/master

Create a New Branch

git checkout -b "my_branch"

Make your changes. Once ready to commit, follow these steps:

Format your code (see Code Formatting section). Alternatively, precommit hooks may help to not forget about formatting upon pushing the code (see Installing Pre-commit Hooks section). Make sure that all corresponding tests are passing (see Testing section)
Verify your changes:
```
git diff
git status
```
Add modified files:
- To add all changed files:
```
git add -u
```
- To add a specific new file (e.g., new.cc):
```
git add new.cc
```
Check staged files:
```
git status
```

Commit and push your changes:

git commit -m "Add a useful description"
git push origin my_branch

Open a Pull Request on GitHub.
Add labels to the PR.

Use the label to trigger CI checks.
Use to specify regular expressions for ctest -R to ensure faster CI runs.

Testing

To run tests in verbose mode, execute:

ctest -V

To run specific tests based on application names (e.g. mp-advec-diff) or regular expressions, use the -R flag:

ctest -R mp-advec-diff

How to Work with CMake Presets

CMake presets simplify project configuration by standardizing how builds are set up across different environments and developers.

List Available Presets

To view all available configure/build/test presets defined in CMakePresets.json and CMakeUserPresets.json:

cmake --list-presets -S <path-to-mpdg-source>

This shows you a list of named presets like user-release, user-debug, etc., along with descriptions and associated build directories.

Configure with a Preset

To configure your project using a specific preset (e.g. user-release), run:

cmake --preset user-release -S <path-to-mpdg-source>

This:

Uses the settings defined in the user-release preset
Sets the build directory automatically (as defined in the preset)
Applies the correct compiler, flags, and paths

Replace ‘’ with the path to your source directory if you’re not inside the build folder.

Tip: Setting up your own presets

If you haven’t yet set up your user-specific library paths, copy the provided template and adjust it:

cp CMakeUserPresets.json.template CMakeUserPresets.json
# then edit CMakeUserPresets.json to match your local environment

Code Formatting

Ensure that clang-format and autopep8 are installed. We use the clang-format version provided by deal.II (v16), which can be installed via the following script:

🔗 Download clang-format

Once installed, format your code by running:

scripts/formatting/format-all

How to use `clang-tidy` to check your code

To run clang-tidy on your code, you typically need a compile_commands.json file, which describes how each file in your project is compiled. You can generate this using CMake:

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON #...

Navigate to the root directory of MeltPoolDG, then run clang-tidy on the library with:

cd MeltPoolDG-dev
bash scripts/utilities/run_clang_tidy.sh <build_directory> <number_of_processes>

providing the <build_directory> e.g. build_release and the <number_of_processes> for the check e.g. 4. The output will be written to ./<build_directory>/clang-tidy-detailed.log and ./<build_directory>/clang-tidy.log. Make sure that you don’t produce any warnings.

Installing Pre-commit Hooks

Ensure you have pre-commit installed. Then, install the hooks by executing the following command in the root directory of the repository:

pre-commit install

Useful GIT commands

Rebasing Your Branch onto the Latest `master`

If you’re working on my_branch and need to update it with the latest master, follow these steps.

⚠ Warning: If you are unfamiliar with rebasing, create a backup before proceeding.

Ensure you are on the correct branch:
```
git branch
```

Commit any local changes:

git add -u
git commit -m "Save local changes"

Fetch the latest changes:
```
git fetch origin
```
Start the rebase process:
```
git rebase -i origin/master
```
If there are no conflicts, force-push the rebased branch:
```
git push -f origin my_branch
```

Handling Merge Conflicts

If you encounter a merge conflict in my_file.hpp:

Open the file and manually resolve the conflict by removing conflict markers (<<<<<<<, =======, >>>>>>>).
Stage the resolved file:
```
git add my_file.hpp
```
Continue rebasing:
```
git rebase --continue
```
Repeat as needed until the rebase completes successfully.
Force-push your changes:
```
git push -f origin my_branch
```

Squashing Commits into One

To squash multiple commits into a single commit:

🔗 Follow this guide.

⚠ Warning: Squashing rewrites commit history. If unsure, create a backup before proceeding.

Happy coding! 🎉