Contributing guide

Note

Large parts of this document came from the Xarray Contributing Guide and xbatcher Contributing Guide , which is based on the Pandas Contributing Guide.

Bug reports and feature requests

To report bugs or request new features, head over to the cupy-xarray repository.

Contributing code

GitHub has instructions for installing git, setting up your SSH key, and configuring git. All these steps need to be completed for you to work between your local repository and GitHub.

Forking

You will need your own fork to work on the code. Go to the cupy-xarray project page and hit the Fork button. You will need to clone your fork to your machine:

git clone git@github.com:yourusername/cupy-xarray.git
cd cupy-xarray
git remote add upstream git@github.com:xarray-contrib/cupy-xarray.git

This creates the directory cupy-xarray and connects your repository to the upstream (main project) cupy-xarray repository.

Creating a development environment

To test out code changes, you’ll need to build cupy-xarray from source, which requires a Python environment. If you’re making documentation changes, you can skip to Contributing to the documentation but you won’t be able to build the documentation locally before pushing your changes.

Creating a Python Environment

Before starting any development, you’ll need to create an isolated cupy-xarray development environment:

First we’ll create and activate the build environment:

conda env create --file ci/requirements/environment.yml
conda activate cupy-xarray-tests

At this point you should be able to import cupy-xarray from your locally built version.

This will create the new environment, and not touch any of your existing environments, nor any existing Python installation.

To view your environments:

conda info --envs

To return to your base environment:

conda deactivate

See the full conda docs here.

Setting up pre-commit

We use pre-commit to manage code linting and style. To set up pre-commit after activating your conda environment, run:

pre-commit install

Creating a branch

You want your main branch to reflect only production-ready code, so create a feature branch before making your changes. For example:

git branch shiny-new-feature
git checkout shiny-new-feature

The above can be simplified to:

git checkout -b shiny-new-feature

This changes your working directory to the shiny-new-feature branch. Keep any changes in this branch specific to one bug or feature so it is clear what the branch brings to cupy-xarray. You can have many “shiny-new-features” and switch in between them using the git checkout command.

To update this branch, you need to retrieve the changes from the main branch:

git fetch upstream
git merge upstream/main

This will combine your commits with the latest cupy-xarray git main. If this leads to merge conflicts, you must resolve these before submitting your pull request. If you have uncommitted changes, you will need to git stash them prior to updating. This will effectively store your changes, which can be reapplied after updating.

Running the test suite

cupy-xarray uses the pytest framework for testing. You can run the test suite using:

pytest cupy-xarray

Contributing documentation

We greatly appreciate documentation improvements. The docs are built from the docstrings in the code and the docs in the doc directory.

To build the documentation, you will need to requirements listed in ci/doc.yml. You can create an environment for building the documentation using:

conda env create --file ci/doc.yml
conda activate cupy-xarray-docs

You can then build the documentation using:

cd docs
make html

Contributing changes

Once you’ve made changes, you can see them by typing:

git status

If you have created a new file, it is not being tracked by git. Add it by typing:

git add path/to/file-to-be-added.py

The following defines how a commit message should be structured:

  • A subject line with < 72 chars.

  • One blank line.

  • Optionally, a commit message body.

Now you can commit your changes in your local repository:

git commit -m

When you want your changes to appear publicly on your GitHub page, push your commits to a branch off your fork:

git push origin shiny-new-feature

Here origin is the default name given to your remote repository on GitHub. You can see the remote repositories:

git remote -v

If you navigate to your branch on GitHub, you should see a banner to submit a pull request to the cupy-xarray repository.