Skip to content

Latest commit

 

History

History
91 lines (62 loc) · 4.14 KB

CONTRIBUTING.md

File metadata and controls

91 lines (62 loc) · 4.14 KB
Raw

How to contribute

We welcome new contributions to xDEM that is still very much in expansion! Below is a guide to contributing to xDEM step by step, ensuring tests are passing and the documentation is updated.

Overview: making a contribution

The technical steps to contributing to xDEM are:

  1. Fork GlacioHack/xdem and clone your fork repository locally.
  2. Set up the development environment (see section "Setup" below),
  3. Create a branch for the new feature or bug fix,
  4. Make your changes,
  5. Add or modify related tests in tests/ (see section "Tests" below),
  6. Add or modify related documentation in doc/ (see section "Documentation" below),
  7. Commit your changes,
  8. Run pre-commit separately if not installed as git hook (see section "Linting" below),
  9. Push to your fork,
  10. Open a pull request from GitHub to discuss and eventually merge.

Development environment

xDEM currently supports Python versions of 3.10 to 3.12 (see dev-environment.yml for detailed dependencies), which are tested in a continuous integration (CI) workflow running on GitHub Actions.

When you open a PR on xDEM, a single linting action and 9 test actions will automatically start, corresponding to all supported Python versions (3.10, 3.11 and 3.12) and OS (Ubuntu, Mac, Windows). The coverage change of the tests will also be reported by CoverAlls.

Setup

With mamba

Clone the git repo and create a mamba environment (see how to install mamba in the mamba documentation):

git clone https://github.com/GlacioHack/xdem.git
cd xdem
mamba env create -f dev-environment.yml  # Add '-n custom_name' if you want.
mamba activate xdem-dev  # Or any other name specified above

With pip

git clone https://github.com/GlacioHack/xdem.git
cd xdem
make install

Please note: pip installation is currently only possible under python3.10.

Tests

At least one test per feature (in the associated tests/test_*.py file) should be included in the PR, using pytest (see existing tests for examples). The structure of test modules and functions in tests/ largely mirrors that of the package modules and functions in xdem/.

To run the entire test suite, run pytest from the root of the repository:

pytest

Running pytest will trigger a script that automatically downloads test data from https://github.com/GlacioHack/xdem-data used to run all tests.

RichDEM should only be used for testing purposes within the xDEM project. The functionality of xDEM must not depend on RichDEM.

Documentation

If your changes need to be reflected in the documentation, update the related pages located in doc/source/. The documentation is written in MyST markdown syntax, similar to GitHub's default Markdown (see MyST-NB for details).

To ensure that the documentation is building properly after your changes, if you are on Linux, you can run pytest tests/test_doc.py, which is equivalent to building directly calling sphinx-build source/ build/html/ from the doc/ folder. On Windows and Mac, the documentation is not maintained, so you can wait to open the PR for it to be checked on Linux by the CI.

Formatting and linting

Install and run pre-commit from the root of the repository (such as with mamba install pre-commit, see pre-commit documentation for details), which will use .pre-commit-config.yaml to verify spelling errors, import sorting, type checking, formatting and linting:

pre-commit run --all

You can then commit and push those changes. Optionally, pre-commit can be installed as a git hook to ensure checks have to pass before committing.

Final steps

That's it! If the tests and documentation are passing, or if you need help to make those work, you can open a PR.

We'll receive word of your PR as soon as it is opened, and should follow up shortly to discuss the changes, and eventually give approval to merge. Thank you so much for contributing!

Rights

The license (see LICENSE) applies to all contributions.