Contributing

Setting up the repository

To contribute to canesm-processor, start by creating a fork of the main repository. Go to LandonRieger/canesm-processor and press the fork button on the top right. This will create a copy of the repository in your local Gitlab namespace.

Your new fork will open and then you can clone the forked repository. The command will look something like

git clone git@gitlab.com:YOURNAME/canesm-processor.git

Installing a Developer Version

It is recommended to create a fresh environment for development and install an editable copy of canesm-processor into that environment. For conda this looks like:

conda create -n canproc -c conda-forge python=$VERSION xarray numpy pandas dask pydantic pytest pytest-cov sphinx=8.0.2
conda activate canproc
pip install -e .[dev]

The [dev] will install optional development dependencies such as those required to build the docs.

Developing a feature

To create a new feature, you should work on a feature branch. Ideally each branch is isolated to a single feature. You can make a new branch with

git checkout -b shiny-new-feature

which will then create a new branch with the name shiny-new-feature. The branch only exists on your local fork. Don’t worry about how many commits you make to the branch or how messy they are, when it is time to merge the branch into the main repository all of the commits will be squashed into a single one and you will have the opportunity to write a new description.

## Creating a pull request Once you have made a commit to your branch and pushed the changes to your fork, you are ready to make a pull request. This can be done from the pull requests page on the main repository. If your pull request is still a work in progress, prepend the title with WIP:

In addition to the feature, we require that all pull requests contain tests for the feature (if applicable), as well as updates to the documentation (if applicable)

Code Style

For Python code we follow the black code style.

For both we recommend using the provided pre-commit hook to automatically both format and check your code. These can be installed with

pip install pre-commit

You can run the formatters manually by typing

pre-commit run -a

You will see output that looks like

black....................................................................Passed

If you want, you can then run

pre-commit install

which will set up the pre commit hooks to run automatically every-time you commit to the repository.

We highly recommend using the pre commit hooks. On every pull request these checks are automatically ran, and the code will not be merged in if any fail. Using the pre commit hooks locally saves everyone time.

Adding Docs

Documentation is written in sphinx using reStructuredText and published via GitLab Pages. You can build a local version by running the following from the top level folder.

sphinx-build -b html docs/source docs/public