Contributing to Fastscapelib#

The Fastscapelib project is open source and welcomes your feedback and/or contributions! There are many ways to contribute to the development of the library, including bug reports, bug fixes, documentation improvements, enhancement suggestions, and other ideas.

This short guide will help you getting started. Please check online resources and tutorials for more details about the developer tools that are used here.

Bug Reports, Suggestions and Discussions#

Fastscapelib’s source repository is hosted on GitHub. This is also where you can submit bug reports, enhancement ideas or general usage questions either in the issue tracker or in the discussions.

Tip

Check this stack-overflow article and this blog post by Matthew Rocklin for tips on how to write good bug reports.

GitHub supports the markdown syntax for formatting code, add links, etc. This is helpful for writing clear reports.

Fastscapelib’s Git Repository#

Note

Contributing to the code or documentation requires some basic knowledge of Git. You can find many resources and tutorials online for learning Git.

Follow the steps below to get or update Fastscapelib’s source code and prepare your contribution (you can skip steps 1-2-3 if this is not your first contribution):

  1. Go on the Fastscapelib GitHub page and click on the “Fork” button (you need to have an account on GitHub and be logged in).

  2. Clone your Fastscapelib forked Git repository (by default, this will setup a remote origin repository pointing to your fork on GitHub):

$ git clone https://github.com/your-username/fastscapelib
$ cd fastscapelib

  1. Add a new remote upstream repository pointing to the Fastscapelib main repository on GitHub:

$ git remote add upstream https://github.com/fastscape-lem/fastscapelib

  1. Pull the latest updates from the Fastscapelib original repository into your local main branch (you can skip this step if this is your first contribution):

$ git checkout main
$ git pull upstream main

  1. Create a new Git branch in which you will implement your bug fixes, documentation enhancement or new feature:

$ git checkout -b your-branch-name

Creating a Development Environment#

We strongly recommend installing all the dependencies and development tools in a new conda environment created specifically for this project.

You can create a new conda environment with all the dependencies needed for both C++ and Python development by running the following command from the repository’s root directory:

$ conda env create -n fastscapelib-dev -f environment-dev.yml -f environment-python-dev.yml

Note: this doesn’t include a recent C++ compiler supporting the C++17 standard (if you need to install one, you could also use conda for that).

Then activate the conda environment (needed each time you open a new terminal or session):

$ conda activate fastscapelib-dev

Pre-Commit#

Fastscapelib also provides a configuration file for setting up Git hooks via pre-commit. This will automatically check and format the C++ and Python code before committing, using Clang-Format and Black respectively.

pre-commit has to be installed separately in your activated conda environment:

$ conda install pre-commit -c conda-forge

Then run the following command once to configure the Git hooks:

$ pre-commit install

Contributing to the Code Base#

Once the development environment is created and activated, each time after editing the code you might want to perform one or several of the following tasks depending on what has been added, removed or modified:

To run mypy:

$ python -m mypy .

Contributing to the Documentation#

The documentation is written in various formats:

It is built using Sphinx, MyST-Parser, MyST-NB as well as a few other Sphinx extensions.

The API reference documentation is generated automatically from the docstrings found in the code using Doxygen, Breathe and the Sphinx autodoc extension.

The docstrings follow the Doxygen style conventions for the C++ API and the Numpydoc style guide for the Python API.

You can install all the documentation development tools in a new conda environment with the following command:

$ conda env create -f doc/environment.yml
$ conda activate fastscapelib-docs

Fastscapelib provides a Makefile to help building the documentation locally with the following commands:

$ cd doc
$ make html

This will run doxygen to generate xml files from the C++ docstrings and then sphinx-build to generate API source files, run the notebook examples and render all the source files as html.

If the build completed successfully, you can then open _build/html/index.html with your web-browser to visualize the output files.

Building the documentation for the first time may take a little while. During the next builds, Sphinx will only rebuild the modified source files. To trigger a full build from scratch, run:

$ make clean
$ make html

Contributing Your Changes to Fastscapelib#

Once you are ready to submit your fixes or changes to the Fastscapelib repository, you can add and commit it using Git:

$ git add <files_or_paths_to_add>
$ git commit -m "replace this by a meaningful commit message"

Tip

Run the git status command to check which files have been changed.

If you configured pre-commit, the last command will automatically check and reformat the code (after installing the auto-formatting tools if needed). In case some code is reformatted, you’ll need to repeat the two commands above.

At any time you can push the last commits of your local branch to your fork on GitHub with:

$ git push origin your-branch-name

Then, if you visit again the Fastscapelib repository (or your fork) on GitHub you should see an invite to create a new pull-request from your uploaded branch.

It is possible that new commits are automatically added in the pull-request by the pre-commit continuous integration service to reformat some files. It that’s the case, don’t forget to pull these commits to keep your local branch synchronized:

$ git pull origin your-branch-name

If you need to make further changes, you can repeat the add / commit / push Git operations. The pull-request will be automatically updated with the new changes.

Continuous Integration#

After each commit in a pull-request or after merging a pull request, all the following tasks are run automatically using GitHub Actions:

  • build and run the C++ tests on Linux, Mac and Windows for different compilers and/or versions

  • build the Python package and run the Python tests on Linux, Mac and Windows for different Python versions

  • run pre-commit to check for code formatting inconsistencies

  • run mypy for checking Python type hints

  • build the documentation on readthedocs