Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
129 lines (98 loc) · 5.39 KB

CONTRIBUTING.md

File metadata and controls

129 lines (98 loc) · 5.39 KB
Raw

Contributing to the pyrealm package

We welcome contributions to improving and extending the pyrealm package. This page provides an overview of the key components for contributing to pyrealm and then links to more details on the package website: https://pyrealm.readthedocs.io/

The development overview page on the website provides an expanded overview of this page, including more details on setting up your computer to develop pyrealm.

Contributing code

All code contributions are added to pyrealm through this Github repository. You might want to help fix an existing bug or add a requested feature or have your own ideas to add to pyrealm. Whatever you want to do, the first thing is to open a new issue or post on an existing issue and start a conversation with the other developers. We are really keen to engage with new contributors and to help get new code into pyrealm in the smoothest possible way.

See the development overview page for more details.

Quick Start

The pyrealm package uses the poetry tool for package management. Getting a simple development environment should involve:

  • Installing python: pyrealm requires python >3.10 and we currently support versions python <=3.11.
  • Installing poetry: although the poetry tool manages the versions of all the package requirements, the version of poetry itself is not managed. Developers should all ensure that they install the same version of poetry to avoid version incompatibility issues. We currently use poetry 1.8.2.
# Download the repository
git clone https://github.com/ImperialCollegeLondon/pyrealm.git
# Move into the repository root
cd pyrealm
# Use poetry to install the package requirements
poetry install
# Check the installation has succeeded.
poetry run pytest

See the installation page for more details on setting up the development environment and developing pyrealm.

The pyrealm_build_data package

The pyrealm repository also includes the pyrealm_build_data package that is used to provide data files for use in testing and documentation. See the pyrealm_build_data page for more details on the available data and usage.

Code testing

We use the pytest package to provide unit testing for the pyrealm package. The test suite lives in the tests directory and all new and updated code should include tests to check that the code works as intended. The test suite also includes regression testing against previous implementations and a set of tests for code profiling and performance benchmarking.

We use the pytest-cov plugin to generate coverage reports on pyrealm code, to check how well the code is covered by the test suite. We use codecov to record code coverage and report on changes in coverage between commits..

See the code testing page for more details.

Code quality checks

The package includes configuration for a set of pre-commit hooks to ensure code commits meet common community quality standards. The pre-commit tool blocks git commits until all hooks pass. You should install these to ensure that your commited code meets these standards.

See the pre-commit configuration page for more details on setting up pre-commit and the hooks used.

Continuous integration

The project uses a GitHub Actions workflow to support continuous integration. The workflow is used to check the code quality, run the unit and regression testing suite and check the documentation builds successfully on all pull requests.

See the GitHub Actions page for more details on the workflow and process.

Profiling and benchmarking

Even if the code works as expected and passes all our tests, it can still be slow! We use code profiling to work out where time is spent when using pyrealm and identify where we can improve performance. We also use benchmarking between pyrealm versions to make sure that changes to the code aren't making it slower. This is run automatically when new code is pulled to the develop or main branches but can also be used to do local profiling and benchmarking.

See the profiling and benchmarking page for more details.

Documentation

We use:

  • The sphinx package to build the pyrealm website on ReadTheDocs.
  • Docstrings to describe the code and automatically generate API descriptions for the website.
  • The doctest package to provide limited examples of code use in docstrings.
  • MyST Markdown notebooks to provide extended usage examples within the website.

See the documentation page for more details.

Release process

We use trusted publishing from Github releases to submit new versions of the package to PyPI. See the release process page for more details on the release process.