xarray-simlab 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.
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.
For now, as the project is still very young, it is also a good place for asking usage questions.
If you wish to contribute to the development of the code and/or the documentation, here are a few steps for setting 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 xarray-simlab repository on GitHub (you need to have an account).
Then clone your fork locally:
$ git clone email@example.com:your_name_here/xarray-simlab.git
Alternatively, if you don’t plan to submit any modification, you can clone the original xarray-simlab git repository:
$ git clone firstname.lastname@example.org:benbovy/xarray-simlab.git
$ conda create -n xarray-simlab_dev python attrs numpy xarray zarr dask -c conda-forge $ conda activate xarray-simlab_dev
Then install xarray-simlab locally (in development mode) using
$ cd xarray-simlab $ python -m pip install -e .
To make sure everything behaves as expected, you may want to run xarray-simlab’s unit tests locally using the pytest package. You can first install it with conda:
$ conda install pytest pytest-cov pytest-mock -c conda-forge
Then you can run tests from the main xarray-simlab directory:
$ pytest xsimlab --verbose
Contributing to code¶
Below are some useful pieces of information in case you want to contribute to the code.
Once you have setup 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.
Once you are done with the changes, you can commit your changes to git and push your branch to your xarray-simlab 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).
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).
xarray-simlab supports Python versions 3.6 and higher. It is not compatible with Python versions 2.x. We don’t plan to make it compatible with Python 2.7.x.
xarray-simlab’s uses unit tests extensively to make sure that every part of the code behaves as we expect. Test coverage is required for all code contributions.
Unit tests are written using pytest style (i.e., mostly using the
statement directly) in various files located in the
conftest.py defines some
process decorated classes,
xarray.Dataset objects that can be used as fixtures for testing.
You can run the tests locally from the main xarray-simlab directory:
$ pytest xsimlab --verbose
All the tests are also executed automatically on continuous integration platforms on every push to every pull request on GitHub.
Everything (i.e., classes, methods, functions…) that is part of the public API should follow the numpydoc standard when possible.
Code Formatting & linting¶
xarray-simlab uses black and flake8 to ensure a consistent code format
throughout the project. Both of these tools can be installed with either
pip. Once installed in your development environment, your can
run them from the root of the xarray-simlab repository:
$ black . $ flake8
to auto-format your code. For convenience, many editors have plugins that will
black as you edit files.
flake8 reports warnings and/or errors about code formatting. It may also
detect other programming errors.
Like unit tests, These tools are also run on continuous platforms for every code change submission.
Contributing to documentation¶
To build the documentation locally, first install requirements (for example here in a separate conda environment):
$ conda env create -n xarray-simlab_doc -f doc/environment.yml $ conda activate xarray-simlab_doc
Then build documentation with
$ cd doc $ make html
The resulting HTML files end up in the
You can now make edits to rst files and run
make html again to update
the affected pages.