Instructions for Contributors

We welcome and support new contributions! 🎉 No matter how small, your contribution is always welcomed!

Before contributing we suggest browsing through the open issues and/or open pull requests to ensure that there isn’t already any related work being done or discussed.

It’s always a good idea to start by opening an issue to discuss before putting a lot of work into implementing something.

Contributors should strive to keep pull requests as self-contained as possible. Thinking of contributing several new features into the package? Great! But each feature deserves its own pull request. And each feature-pull request should come with some tests and documentation of the feature implemented. Tests and documentation are equally valuable as the source code!

Before opening a pull request it’s always a good idea to run the tests locally to catch any potential bugs/errors that might have been introduced. Also, sometimes it’s also a good idea to build the documentation locally to see how new docstrings or any new bits of documentation that you may have added look like. Instructions for doing both of these follow below.

Testing

To run the tests from a local clone of the repository we first need to create a conda environment with all the required dependencies.

We create the environment by calling

conda env create --prefix ./env --file environment-ci.yml

from the repository’s local clone main directory. Then we activate it via

conda activate ./env

We then install both the package in this environment as well as the pytest package:

python -m pip install .
python -m pip install pytest

Now we can run the tests with

python -m pytest tests/

If we also want to run the doctests (that is, the tests that appear as examples in various docstrings), we can use

python -m pytest --doctest-modules tests/ regional_mom6/

Documentation

To build the docs from a local clone of the repository we first need to create a conda environment after we first navigate to the docs directory of our local repository clone.

cd docs
conda create --name docs-env --file requirements.txt

We activate this environment and install the package itself as an editable install (pip install -e).

conda activate docs-env
pip install -e ..

Now we can build the docs via make:

make html

and upon successful build, we preview the documentation by opening _build/html/index.html in our favorite browser.

Alternatively, instead of creating a conda environment, we can install the required dependencies for the docs via pip; the rest is same, that is

cd docs
pip install -r requirements.txt
pip install -e ..
make html