Contributor Guide#

xgcm is meant to be a community driven package and we welcome feedback and contributions.

Did you notice a bug? Are you missing a feature? A good first starting place is to open an issue in the github issues page.

Want to show off a cool example using xgcm? Please consider contributing to xgcm-examples. Notebooks from there will be rendered in pangeo-gallery.

In order to contribute to xgcm, please fork the repository and submit a pull request. A good step by step tutorial for this can be found in the xarray contributor guide.

Environments#

The easiest way to start developing xgcm pull requests, is to install one of the conda environments provided in the ci folder:

conda env create -f ci/environment.yml

Activate the environment with:

conda activate test_env_xgcm

Finally install xgcm itself in the now activated environment:

pip install -e .

A good first step is to check if all the tests pass locally:

pytest -v

And now you can develop away…

Code Formatting#

We use black as code formatter and pull request will fail in the CI if not properly formatted.

All conda environments contain black and you can reformat code using:

black xgcm

pre-commit provides an automated way to reformat your code prior to each commit. Simply install pre-commit:

pip install pre-commit

and install it in the xgcm root directory with:

pre-commit install

and your code will be properly formatted before each commit.

Building the documentation locally#

Install the following conda environment:

conda env create -f doc/environment.yml

Now activate the environment with:

conda activate test_env_xgcm_docs

Install xgcm itself in the now activated environment:

pip install -e .

Navigate to the docs folder and build the docs:

cd doc
make clean
make html

You can now open doc/_build/html/index.html in a web browser.

How to release a new version of xgcm (for maintainers only)#

The process of releasing at this point is very easy.

We need only two things: A PR to update the documentation and a release on github.

Make sure that all the new features/bugfixes etc are appropriately documented in doc/whats-new.rst, add the date to the current release and make an empty (unreleased) entry for the next minor release as a PR.
Navigate to the ‘tags’ symbol on the repos main page, click on ‘Releases’ and on ‘Draft new release’ on the right. Add the version number and a short description and save the release.

From here the github actions take over and package things for Pypi. The conda-forge package will be triggered by the Pypi release and you will have to approve a PR in xgcm-feedstock. This takes a while, usually a few hours to a day.

Thats it!

How to synchronize examples from xgcm-examples#

Most of the example notebooks in this documentation are located in the seperate repo xgcm-examples, which is automatically linked to pangeo gallery. These examples are synced into this documentation using git submodules. Currently updates in the example repo need to be manually synced to this repo with the following steps:

From the xgcm root directory do:

cd doc/xgcm-examples

If this directory is empty, it means your original install did not pull the submodule; to configure the submodule, do:

git submodule update --init

You are now in a seperate git repository and can pull all updates:

git pull

Now navigate back to the xgcm repo:

cd -

And commit, push like usual to create a pull request.:

Contributor Guide

Contents