Skip to content

If you are a developer wanting to contribute to the diffwofost package, this guide will help you get started. First check out the contribution guidelines in Contributing guide and the Project setup to get familiar with the package structure and development practices.

Installation in development mode

To install the package in development mode, you need to clone the source code and install the package in development mode:

git clone https://github.com/WUR-AI/diffWOFOST.git
cd diffWOFOST
pip install -e .[dev]  ## install with development dependencies
pip install -e .[docs]  ## install with documentation dependencies

GitHub collaboration workflow

We use a GitHub collaboration workflow based on feature branches and pull requests. When starting adding a new feature or fixing a bug, create a new branch from main branch. When your changes are ready, create a pull request to merge your changes back into main branch. Make sure to ask for at least one review from another team member before merging your pull request.

Running the tests

  • Tests should be put in the tests folder.
  • The testing framework used is PyTest
  • The project uses GitHub action workflows to automatically run tests on GitHub infrastructure against multiple Python versions. Workflows can be found in .github/workflows directory.
  • Relevant section in the guide
  • To run the tests locally, you need to make sure that you have installed the development dependencies as described in the Installation in development mode section. Then, inside the package directory, run:
pytest -v

to run all tests with verbose output. To run an individual test file, run:

pytest -v tests/test_my_module.py

Test config and test data

The config file tests/conftest.py contains configurations for testing. The main configurations are related to:

  • the test data, which is downloded from pcse github repository,
  • the device used for testing (cpu or gpu), and
  • the amount of tests to run (full_wofost72_test or --fast).

In the github workflow build.yaml the tests are run with --fast option, which runs a subset of the tests on github runner in a pull request or after merging to main branch.

In the github workflow full-test.yaml the tests are run with full_wofost72_test option, which might takes a long time to run. So, this workflow is only triggered manually when needed, for example before a release.

Linters

For linting and sorting imports we will use ruff. Running the linters requires an activated virtual environment with the development tools installed.

# linter
ruff check .

# linter with automatic fixing
ruff check . --fix

# check formatting only
ruff format --check . --diff

Documentation page

  • Documentation should be put in the docs/ directory.
  • We recommend writing the documentation using Google style docstrings.
  • The documentation is set up with the MkDocs.
  • .mkdocs.yml is the MkDocs configuration file. When MkDocs is building the documentation this package and its development dependencies are installed so the API reference can be rendered.
  • Make sure you have installed the documentation dependencies as described in the Installation in development mode section. Then, inside the package directory, run:
# Build the documentation
mkdocs build

# Preview the documentation
mkdocs serve

Click on the link provided in the terminal to view the documentation page.

Coding style conventions and code quality

Continuous code quality

Sonarcloud is used to perform quality analysis and code coverage report

  • sonar-project.properties is the SonarCloud configuration file
  • .github/workflows/sonarcloud.yml is the GitHub action workflow which performs the SonarCloud analysis