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:
Make sure your conda is up to date (
conda update conda
)Make sure that you have cloned the repository
cd
to the cupy-xarray source directory
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.