Contributing to pyRTE-RRTMGP

Thanks for considering making a contribution to pyRTE-RRTMGP!

This document contains information about the many ways you can support pyRTE-RRTMGP, including how to report bugs, propose new features, set up a local development environment, contribute to the documentation, run and update tests, and make a new release.

How to Report a Bug

Please file a bug report on the GitHub repository. If possible, your issue should include a minimal, complete, and verifiable example of the bug.

How to Contribute a Patch That Fixes a Bug

Please fork this repository, branch from main, make your changes, and open a GitHub pull request against the main branch.

How to Propose a New Feature

Please file a feature request on the GitHub page.

How to Contribute New Features

Please fork this repository, branch from main, make your changes, and open a GitHub pull request against the main branch.

Pull Requests for new features should include tests and documentation.

How to Contribute to the Documentation

The documentation uses Sphinx with MystMD for Markdown support. The source for the documentation is in the docs directory.

To build the documentation locally, first install the required documentation dependencies with mamba:

mamba env create -f docs/environment-docs.yml

which will install pyRTE’s dependencies and the package itself in editable mode, which means that any changes you make to the package will be reflected in the documentation build right after you make them, without needing to reinstall the package.

Enter the newly created environment:

mamba activate pyrte_rrtmgp_docs

and build the documentation:

cd docs
make html

The built documentation will be located in docs/build/html. You can use a web browser to open the index.html file in this directory to view the documentation.

The documentation is automatically built and deployed to Read the Docs whenever a new commit is pushed to the main branch. The configuration for the Read the Docs build is in the .readthedocs.yml file.

How to Make a New Release (for project maintainers)

For maintainers:

First, check for common issues that might arise between RTE-RRTMGP (Fortran) and pyRTE-RRTMGP (Python), use the check_binds.py script. This script will compare the functions in the Fortran code with the functions in the Python bindings. The script will output any missing functions or functions that have been removed.

python check_binds.py --c_headers /path/to/rrtmgp_kernels.h /path/to/rte_kernels.h --pybind /path/to/pybind_interface.cpp

For more details, see Maintaining compatibility between pyRTE-RRTMGP and RTE-RRTMGP.

After checking the compatibility, follow these steps to make a new release:

  1. Update the version number (using https://semver.org/) in pyproject.toml and conda.recipe/meta.yaml. Also update CITATION.cff as necessary (for Zenodo integration). e.g. version = "1.1.0" in pyproject.toml and version: 1.1.0 in meta.yaml and CITATION.cff.

  2. Create a new tag with the version number off the main branch on GitHub, adding a v before the version number (e.g. v1.1.0).

  3. Create a new release, using the “Draft a new release” button in https://github.com/earth-system-radiation/pyRTE-RRTMGP/releases adding a v before the release (e.g. v1.1.0).

  4. Review and update the the release notes as necessary, publish the release, and set it as the latest release.

A PR to update the conda forge recipe should be created automatically by regro-cf-autotick-bot. It can take several hours for the bot to detect the update and create the PR!

The feedstock for the conda package is located at https://github.com/conda-forge/pyRTE_RRTMGP-feedstock. Once the PR on the feedstock repo passes all tests, one of the pyRTE-RRTMGP maintainers can merge the PR and the new version of the package will be available on conda-forge.

The documentation on https://pyrte-rrtmgp.readthedocs.io/ will update automatically. To make changes to the build process and other aspects of the readthedocs configuration, see the .readthedocs.yml file.