Contributing#

All contributions are welcome, no matter how small. Whether you are fixing a typo, reporting a bug, or implementing a new feature, your help is appreciated.

Ways to contribute#

In the community:

In the codebase:

Improve the documentation
Fix bugs
Implement new features

Contributing to the code#

For a general overview of contributing to GitHub projects, see the GitHub contributing guide.

Tip

If you are new to the project, look for issues tagged “good first issue”. These are typically straightforward and a great way to get started.

Fork the repository

Forking creates a personal copy of the repository where you can freely make changes.
Clone your fork and add the upstream remote
```
git clone https://github.com/[your_username]/FESTIM
cd FESTIM
git remote add upstream https://github.com/festim-dev/FESTIM
```
Replace [your_username] with your GitHub username. The upstream remote lets you pull in changes from the main repository to keep your fork up to date:
```
git fetch upstream
git merge upstream/main
```
Create a branch

Always work on a dedicated branch rather than directly on main:
```
git checkout -b my-feature-branch
```
Set up your development environment

Create a dedicated conda environment and install FESTIM from conda-forge. This pulls in all required dependencies, including FEniCSx:
```
conda create -n festim-dev
conda activate festim-dev
conda install -c conda-forge festim
```
Then uninstall the conda-managed FESTIM package and replace it with your local clone in editable mode, so that any changes you make are picked up immediately without reinstalling:
```
pip uninstall festim
pip install -e .
```
Note

The -e flag installs the package in editable mode. Python will import directly from your local source tree, meaning you do not need to reinstall after each change.

Make your changes

Commit your changes with a clear, descriptive message:

git add [modified files]
git commit -m "Short description of the change"
git push origin my-feature-branch

Test your code

Before opening a PR, run the test suite locally to make sure nothing is broken. See Test suite for more information.
Format your code

FESTIM uses Black for consistent code formatting. See Code formatting for more information.
Optional: build the documentation

If you modified or added documentation, build it locally to verify it renders correctly. See Documentation guide for more information.
Open a PR

Include a clear description of what the PR does and reference any related issues (e.g. Closes #123).
Wait for a maintainer to review your PR

Maintainers will review your changes to ensure correctness and code quality, and may request further modifications. Review time depends on maintainer availability.
Once approved, a maintainer will merge your PR. Congratulations!

Maintainers#

Maintainers are the people with merge rights on the repository:

Remi Delaporte-Mathurin (@RemDelaporteMathurin) – project lead
James Dark (@jhdark)
Vladimir Kulagin (@KulaginVladimir)

Test suite#

FESTIM uses continuous integration (CI) to maintain code quality. Every push to the repository or a pull request triggers the test suite automatically, catching regressions and bugs early. See Atlassian’s CI guide for a general introduction to CI.

All tests live in the test folder at the root of the repository.

Note

Install pytest if you haven’t already:

pip install pytest

Then run the full test suite from the project root:

pytest test/

The tests must pass before a PR can be merged.

When fixing a bug or adding a feature, please add or update tests to cover the new behaviour.

Debugging#

When you find a bug, follow these steps to make things easier for maintainers:

Raise an issue

Opening an issue creates a record of the bug and gives maintainers and contributors a place to troubleshoot, discuss potential fixes, and document workarounds.
Write a test that reproduces the bug

A failing test is the clearest way to demonstrate a bug and verify that your fix works. It also guards against the same bug reappearing in the future.
Fix the bug and open a PR.

Implementing a new feature#

Raise an issue

Before writing any code, open an issue to discuss the feature with the maintainers. Someone may already be working on it, or the maintainers may have context that shapes the design.
Make your changes and update the documentation if needed.
Write tests to cover the new feature.
Open a PR.

Code formatting#

FESTIM uses Black to enforce a consistent code style, which reduces noise in code reviews and keeps the codebase readable.

Install Black:

pip install black

Format a single file:

black my_script.py

Format all files in the current directory:

black .

Check formatting without modifying any files:

black --check .

Tip

If you use Visual Studio Code, install the Black Formatter extension and enable Format on Save to apply Black automatically whenever you save a file.

Documentation guide#

The documentation is often the first thing a user encounters. Keeping it accurate, clear, and up to date is as important as keeping the code correct.

The docs are written in reStructuredText and live in the docs folder. They are built with Sphinx and hosted on Read the Docs, which rebuilds automatically on every commit and pull request.

Setting up the documentation environment

Note

Create a dedicated conda environment with all documentation dependencies:

conda env create -f docs/environment.yml
conda activate festim2-docs

Building the docs

From the docs/source directory:

cd docs/source
make html

Or from the docs directory in a single step:

cd docs
sphinx-build -b html source build

The generated HTML will be in docs/source/_build/html. Open index.html in your browser to preview the result.

To remove all build artefacts and start from scratch:

cd docs/source
make clean

Running doctests

Verify that all code examples in the documentation execute correctly:

cd docs/source
make doctest

Or equivalently:

cd docs
sphinx-build -b doctest source build

Documentation checklist

When contributing to the documentation, make sure to:

Write clearly and concisely
Use correct reStructuredText syntax
Update existing pages when behaviour changes
Add documentation for any new features
Run the doctests to confirm all code examples are correct