Contributor Guide¶
Xoak is an open-source project. Contributions are welcome, and they are greatly appreciated!
You can contribute in many ways, e.g., by reporting bugs, submitting feedbacks, contributing to the development of the code and/or the documentation, etc.
This page provides resources on how best to contribute.
Issues¶
The Github issue tracker is the right place for reporting bugs and for discussing about development ideas. Feel free to open a new issue if you have found a bug or if you have suggestions about new features or changes.
If you are reporting a bug, please include:
Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting, specifically the Python interpreter version, installed libraries, and Xoak version.
Detailed steps to reproduce the bug.
If you can write a demonstration test that currently fails but should pass, that is a very useful commit to make as well, even if you cannot fix the bug itself.
For now, as the project is still very young, it is also a good place for asking usage questions.
Development environment¶
If you wish to contribute to the development of the code and/or the documentation, here are a few steps for setting up a development environment.
Fork the repository and download the code¶
To further be able to submit modifications, it is preferable to start by forking the Xoak repository on GitHub (you need to have an account).
Then clone your fork locally:
$ git clone git@github.com:your_name_here/xoak.git
Alternatively, if you don’t plan to submit any modification, you can clone the original Xoak git repository:
$ git clone git@github.com:xarray-contrib/xoak.git
Install¶
To install the dependencies, we recommend using the conda package manager with the conda-forge channel. For development purpose, you might consider installing the packages in a new conda environment:
$ conda create -n xoak_dev python xarray dask scipy scikit-learn -c conda-forge
$ conda activate xoak_dev
Then install Xoak locally (in development mode) using pip:
$ cd xoak
$ python -m pip install -e .
Pre-commit¶
Xoak provides a configuration for pre-commit, which can be used to ensure that code-style and code formatting is consistent.
First install pre-commit:
$ conda install pre-commit -c conda-forge
Then run the following command to activate it in the current repository:
$ pre-commit install
From now on pre-commit will run whenever you commit with git.
Contributing to code¶
Below are some useful pieces of information in case you want to contribute to the code.
Local development¶
Once you have set up the development environment, the next step is to create a new git branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
Submit changes¶
Once you are done with the changes, you can commit your changes to git and push your branch to your Xoak fork on GitHub:
$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature
(note: this operation may be repeated several times).
When committing, pre-commit will re-format the files if necessary.
We you are ready, you can create a new pull request through the GitHub website (note that it is still possible to submit changes after your created a pull request).
Contributing to documentation¶
Xoak uses Sphinx for documentation, hosted on http://readthedocs.org .
Documentation is maintained in the RestructuredText markup language (.rst
files) in the doc folder.
To build the documentation locally, first install some extra requirements:
$ conda install sphinx sphinx_rtd_theme sphinx-autosummary-accessors -c conda-forge
Then build the documentation with make:
$ cd doc
$ make html
The resulting HTML files end up in the build/html directory.
You can now make edits to rst files and run make html again to update
the affected pages.