# Contributions are very welcome We greatly value contributions of any kind. Contributions could include, but are not limited to documentation improvements, bug reports, new or improved code, scientific and technical code reviews, infrastructure improvements, mailing list and chat participation, community help/building, education and outreach. We value the time you invest in contributing and strive to make the process as easy as possible. If you have suggestions for improving the process of contributing, please do not hesitate to propose them. If you have a bug or other issue to report or just need help, please open an issue on the [issues tab on the ESMValCore github repository](https://github.com/ESMValGroup/ESMValCore/issues). If you would like to contribute a new [preprocessor function](develop/preprocessor_function.html.md#preprocessor-function), [derived variable](develop/derivation.html.md#derivation), [fix for a dataset](develop/fixing_data.html.md#fixing-data), or another new feature, please discuss your idea with the development team before getting started, to avoid double work and/or disappointment later. A good way to do this is to open an [issue](https://github.com/ESMValGroup/ESMValCore/issues) on GitHub. ## Getting started See [Installation from source](quickstart/install.html.md#installation-from-source) for instructions on how to set up a development installation. New development should preferably be done in the [ESMValCore](https://github.com/ESMValGroup/ESMValCore) GitHub repository. The default git branch is `main`. Use this branch to create a new feature branch from and make a pull request against. This [page](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow) offers a good introduction to git branches, but it was written for BitBucket while we use GitHub, so replace the word BitBucket by GitHub whenever you read it. It is recommended that you open a [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) early, as this will cause CircleCI to [run the tests](#tests) and [analyse the code](#code-quality), and [readthedocs to build the documentation](#documentation). It’s also easier to get help from other developers if your code is visible in a pull request. [Make small pull requests](https://docs.esmvaltool.org/en/latest/community/review.html#easy-review), the ideal pull requests changes just a few files and adds/changes no more than 100 lines of production code. The amount of test code added can be more extensive, but changes to existing test code should be made sparingly. ### Design considerations When making changes, try to respect the current structure of the program. If you need to make major changes to the structure of program to add a feature, chances are that you have either not come up with the most optimal design or the feature is not a very good fit for the tool. Discuss your feature with the [@ESMValGroup/esmvaltool-coreteam](https://github.com/orgs/ESMValGroup/teams/esmvaltool-coreteam) in an [issue](https://github.com/ESMValGroup/ESMValCore/issues) to find a solution. Please keep the following considerations in mind when programming: - Changes should preferably be [backward compatible](#backward-compatibility). - Apply changes gradually and change no more than a few files in a single pull request, but do make sure every pull request in itself brings a meaningful improvement. This reduces the risk of breaking existing functionality and making [backward incompatible](#backward-compatibility) changes, because it helps you as well as the reviewers of your pull request to better understand what exactly is being changed. - [Preprocessor functions](api/esmvalcore.preprocessor.html.md#preprocessor-functions) are Python functions (and not classes) so they are easy to understand and implement for scientific contributors. - No additional CMOR checks should be implemented inside preprocessor functions, though it is our ambition to make preprocessor functions work with any data that follows the [CF Conventions](https://cfconventions.org/). The input cube is fixed and confirmed to follow the specification in [esmvalcore/cmor/tables](https://github.com/ESMValGroup/ESMValCore/tree/main/esmvalcore/cmor/tables) before applying any other preprocessor functions. This design helps to keep the preprocessor functions and diagnostics scripts that use the preprocessed data from the tool simple and reliable. See [CMOR table configuration](quickstart/configure.html.md#cmor-table-configuration) for the mapping from `project` in the recipe to the relevant CMOR table. - The ESMValCore package is based on [iris](https://scitools-iris.readthedocs.io/en/stable/index.html#iris-docs). Preprocessor functions should preferably be small and just call the relevant iris code. This automatically ensures that the preprocessor functions work with data that follows the CF Conventions. Code that is more involved and more broadly applicable than just in the ESMValCore, should be implemented in iris instead. - Any settings in the recipe that can be checked before loading the data should be checked at the [task creation stage](recipe/overview.html.md#diagnostics). This avoids that users run a recipe for several hours before finding out they made a mistake in the recipe. No data should be processed or files written while creating the tasks. - CMOR checks should provide a good balance between reliability of the tool and ease of use. Several [levels of strictness of the checks](develop/fixing_data.html.md#cmor-check-strictness) are available to facilitate this. - Keep your code short and simple: we would like to make contributing as easy as possible. For example, avoid implementing complicated class inheritance structures and [boilerplate](https://stackoverflow.com/questions/3992199/what-is-boilerplate-code) code. - If you find yourself copy-pasting a piece of code and making minor changes to every copy, instead put the repeated bit of code in a function that you can reuse, and provide the changed bits as function arguments. - Be careful when changing existing unit tests to make your new feature work. You might be breaking existing features if you have to change existing tests. Finally, if you would like to improve the design of the tool, discuss your plans with the [@ESMValGroup/esmvaltool-coreteam](https://github.com/orgs/ESMValGroup/teams/esmvaltool-coreteam) to make sure you understand the current functionality and you all agree on the new design. ## Checklist for pull requests To clearly communicate up front what is expected from a pull request, we have the following checklist. Please try to do everything on the list before requesting a review. If you are unsure about something on the list, please ask the [@ESMValGroup/tech-reviewers](https://github.com/orgs/ESMValGroup/teams/tech-reviewers) or [@ESMValGroup/science-reviewers](https://github.com/orgs/ESMValGroup/teams/science-reviewers) for help by commenting on your (draft) pull request or by starting a new [discussion](https://github.com/ESMValGroup/ESMValTool/discussions). In the ESMValTool community we use [pull request reviews](https://docs.esmvaltool.org/en/latest/community/review.html#reviewing) to ensure all code and documentation contributions are of good quality. The icons indicate whether the item will be checked during the [🛠 Technical review](https://docs.esmvaltool.org/en/latest/community/review.html#technical-review) or [🧪 Scientific review](https://docs.esmvaltool.org/en/latest/community/review.html#scientific-review). - 🧪 The new functionality is [relevant and scientifically sound](#scientific-relevance) - 🛠 [The pull request has a descriptive title and labels](#descriptive-pr-title) - 🛠 Code is written according to the [code quality guidelines](#code-quality) - 🧪 and 🛠 [Documentation]() is available - 🛠 Unit [tests]() have been added - 🛠 Changes are [backward compatible](#backward-compatibility) - 🛠 Changed [dependencies have been added or removed correctly](#dependencies) - 🛠 The [list of authors](#authors) is up to date - 🛠 The [checks shown below the pull request](#pull-request-checks) are successful Pull requests introducing a change that causes a recipe to no longer run successfully (*breaking change*), or which results in scientifically significant changes in results (*science change*) require additional items to be reviewed defined in the [backward compatibility policy](https://docs.esmvaltool.org/en/latest/community/backward_compatibility.html#backward-compatibility-policy). These include in particular: - 🛠 Instructions for the release notes to assist *recipe developers* to adapt their recipe in light of the *backward-incompatible change* available. - 🛠 General instructions for *recipe developers* working on *user recipes* to enable them to adapt their code related to *backward-incompatible changes* available (see [ESMValTool_Tutorial: issue #263](https://github.com/ESMValGroup/ESMValTool_Tutorial/issues/263)). - 🛠 Core development team tagged to notify them of the *backward-incompatible change*, and give at least 2 weeks for objections to be raised before merging to the main branch. If a strong objection is raised the backward-incompatible change should not be merged until the objection is resolved. - 🛠 Information required for the “*backward-incompatible changes*” section in the PR that introduces the *backward-incompatible change* available. ## Scientific relevance The proposed changes should be relevant for the larger scientific community. The implementation of new features should be scientifically sound; e.g. the formulas used in new preprocesssor functions should be accompanied by the relevant references and checked for correctness by the scientific reviewer. The [CF Conventions](https://cfconventions.org/) as well as additional standards imposed by [CMIP](https://www.wcrp-climate.org/wgcm-cmip) should be followed whenever possible. ## Pull request title and label The title of a pull request should clearly describe what the pull request changes. If you need more text to describe what the pull request does, please add it in the description. [Add one or more labels](https://docs.github.com/en/github/managing-your-work-on-github/managing-labels#applying-labels-to-issues-and-pull-requests) to your pull request to indicate the type of change. At least one of the following [labels](https://github.com/ESMValGroup/ESMValCore/labels) should be used: bug, deprecated feature, fix for dataset, preprocessor, cmor, api, testing, documentation or enhancement. The titles and labels of pull requests are used to compile the [Changelog](changelog.html.md#changelog), therefore it is important that they are easy to understand for people who are not familiar with the code or people in the project. Descriptive pull request titles also makes it easier to find back what was changed when, which is useful in case a bug was introduced. ## Code quality To increase the readability and maintainability or the ESMValCore source code, we aim to adhere to best practices and coding standards. We include checks for Python and yaml files, most of which are described in more detail in the sections below. This includes checks for invalid syntax and formatting errors. [Pre-commit](https://docs.esmvaltool.org/en/latest/utils/utils.html#pre-commit) is a handy tool that can run all of these checks automatically just before you commit your code. It knows knows which tool to run for each filetype, and therefore provides a convenient way to check your code. Install the pre-commit hooks by running ```bash pre-commit install ``` to make sure your code is formatted correctly and does not contain mistakes whenever you commit some changes. ### Python The standard document on best practices for Python code is [PEP8](https://www.python.org/dev/peps/pep-0008/) and there is [PEP257](https://www.python.org/dev/peps/pep-0257/) for code documentation. We make use of [numpy style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html) to document Python functions that are part of the [ESMValCore API Reference](api/esmvalcore.html.md#api). To check if your code adheres to the standard, go to the directory where the repository is cloned, e.g. `cd ESMValCore`, and run [pre-commit](https://pre-commit.com/): ```default pre-commit run --all ``` We use [ruff](https://docs.astral.sh/ruff/) to automatically format the code and to check for certain bugs and [pyrefly](https://pyrefly.org) for checking that [type hints](https://typing.python.org/en/latest/reference/best_practices.html) are correct. Note that [type hints](https://typing.python.org/en/latest/reference/best_practices.html) are optional, but if you do choose to add them, they should be correct. Both [ruff](https://docs.astral.sh/ruff/) and [pyrefly](https://pyrefly.org) are automatically run by pre-commit. When you make a pull request, adherence to the Python development best practices is checked by running the pre-commit hooks on CircleCI. ### YAML We use [yamllint](https://yamllint.readthedocs.io) to check that YAML files do not contain mistakes. This is automatically run by pre-commit. ### Any text file A generic tool to check for common spelling mistakes is [codespell](https://pypi.org/project/codespell/). This is automatically run by pre-commit. ## Documentation The documentation lives on [docs.esmvaltool.org](https://docs.esmvaltool.org). ### Adding documentation The documentation is [built by readthedocs](https://app.readthedocs.org/projects/esmvalcore/builds/) using [Sphinx](https://www.sphinx-doc.org). There are two main ways of adding documentation: 1. As written text in the directory [doc](https://github.com/ESMValGroup/ESMValCore/tree/main/doc/). When writing [reStructuredText](https://www.sphinx-doc.org/en/main/usage/restructuredtext/basics.html) (`.rst`) files, please try to limit the line length to 80 characters and always start a sentence on a new line. This makes it easier to review changes to documentation on GitHub. 2. As docstrings or comments in code. For Python code, only the [docstrings](https://www.python.org/dev/peps/pep-0257/) of Python modules, classes, and functions that are mentioned in [doc/api](https://github.com/ESMValGroup/ESMValCore/tree/main/doc/api) are used to generate the online documentation. This results in the [ESMValCore API Reference](api/esmvalcore.html.md#api). The standard document with best practices on writing docstrings is [PEP257](https://www.python.org/dev/peps/pep-0257/). For the API documentation, we make use of [numpy style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html). ### What should be documented Functionality that is visible to users should be documented. Any documentation that is visible on [readthedocs](https://docs.esmvaltool.org/projects/ESMValCore) should be well written and adhere to the standards for documentation. Examples of this include: - The [recipe](recipe/overview.html.md#recipe-overview) - Preprocessor [functions](api/esmvalcore.preprocessor.html.md#preprocessor-functions) and their [use from the recipe](recipe/preprocessor.html.md#preprocessor) - [Configuration options](quickstart/configure.html.md#config) - [Installation](quickstart/install.html.md#install) - [Output files](quickstart/output.html.md#outputdata) - [Command line interface](quickstart/run.html.md#running) - [Diagnostic script interfaces](interfaces.html.md#interfaces) - [The experimental Python interface](api/esmvalcore.experimental.html.md#experimental-api) Note that: - For functions that compute scientific results, comments with references to papers and/or other resources as well as formula numbers should be included. - When making changes to/introducing a new preprocessor function, also update the [preprocessor documentation](recipe/preprocessor.html.md#preprocessor). - There is no need to write complete numpy style documentation for functions that are not visible in the [ESMValCore API Reference](api/esmvalcore.html.md#api) chapter on readthedocs. However, adding a docstring describing what a function does is always a good idea. For short functions, a one-line docstring is usually sufficient, but more complex functions might require slightly more extensive documentation. When reviewing a pull request, always check that documentation is easy to understand and available in all expected places. ### How to build and view the documentation Whenever you make a pull request or push new commits to an existing pull request, [readthedocs](https://app.readthedocs.org/projects/esmvalcore/) will automatically build the documentation. The link to the documentation will be shown in the list of checks below your pull request. Click ‘Details’ behind the check `docs/readthedocs.org:esmvalcore` to preview the documentation. If all checks were successful, you may need to click ‘Show all checks’ to see the individual checks. To build the documentation on your own computer, go to the directory where the repository was cloned and run ```bash sphinx-build doc doc/build ``` or ```bash sphinx-build -Ea doc doc/build ``` to build it from scratch. Alternatively, the pixi task `doc` can be used: ```bash pixi run doc ``` Make sure that your newly added documentation builds without warnings or errors and looks correctly formatted. [readthedocs](https://app.readthedocs.org/projects/esmvalcore/) will build the documentation with the command: ```bash sphinx-build -W doc doc/build ``` to catch mistakes that can be detected automatically. The configuration file for [Sphinx](https://www.sphinx-doc.org) is [doc/conf.py](https://github.com/ESMValGroup/ESMValCore/blob/main/doc/conf.py) and the configuration file for ReadTheDocs is [.readthedocs.yaml](https://github.com/ESMValGroup/ESMValCore/blob/main/.readthedocs.yaml). See [Integration with the ESMValCore documentation](https://docs.esmvaltool.org/en/latest/community/code_documentation.html#esmvalcore-documentation-integration) for information on how the ESMValCore documentation is integrated into the complete ESMValTool project documentation on readthedocs. When reviewing a pull request, always check that the documentation checks shown below the pull request were successful. ## Tests To check that the code works correctly, there tests available in the [tests](https://github.com/ESMValGroup/ESMValCore/tree/main/tests) directory. We use [pytest](https://docs.pytest.org) to write and run our tests. Contributions to ESMValCore should be [covered by unit tests](https://the-turing-way.netlify.app/reproducible-research/testing/testing-guidance.html#aim-to-have-a-good-code-coverage). Have a look at the existing tests in the `tests` directory for inspiration on how to write your own tests. If you do not know how to start with writing unit tests, ask the [@ESMValGroup/tech-reviewers](https://github.com/orgs/ESMValGroup/teams/tech-reviewers) for help by commenting on the pull request and they will try to help you. It is also recommended that you have a look at the [pytest](https://docs.pytest.org) documentation at some point when you start writing your own tests. ### Running tests To run the tests on your own computer, go to the directory where the repository is cloned and run the command ```bash pytest ``` or ```bash pixi run test ``` If you are working in a place with a slow internet connection, you may want to skip tests that require an internet connection by adding `-m 'not online'` to the command. To only run tests from a single file, run the command ```bash pytest tests/unit/test_some_file.py ``` If you would like to avoid loading the default pytest configuration from [pyproject.toml](https://github.com/ESMValGroup/ESMValCore/blob/main/pyproject.toml) because this can be a bit slow for running just a few tests, use ```bash pytest -c /dev/null tests/unit/test_some_file.py ``` Use ```bash pytest --help ``` for more information on the available commands. Whenever you make a pull request or push new commits to an existing pull request, the tests in the `tests` directory of the branch associated with the pull request will be run automatically on [CircleCI](https://app.circleci.com/pipelines/github/ESMValGroup/ESMValCore). The results appear at the bottom of the pull request. Click on ‘Details’ for more information on a specific test job. When reviewing a pull request, always check that all test jobs on [CircleCI](https://app.circleci.com/pipelines/github/ESMValGroup/ESMValCore) were successful. ### Test coverage To check which parts of your code are [covered by unit tests](https://the-turing-way.netlify.app/reproducible-research/testing/testing-guidance.html#aim-to-have-a-good-code-coverage), run the command ```bash pytest --cov ``` and open the file `test-reports/coverage_html/index.html` and browse to the relevant file. Note that tracking code coverage slows down the test runs, therefore it is disabled by default and needs to be requested by providing `pytest` with the `--cov` flag. CircleCI will upload the coverage results from running the tests to Codecov. [codecov](https://app.codecov.io/gh/ESMValGroup/ESMValCore/pulls) is a service that will comment on pull requests with a summary of the test coverage. If [codecov](https://app.codecov.io/gh/ESMValGroup/ESMValCore/pulls) reports that the coverage has decreased, check the report and add additional tests. Alternatively, it is also possible to view code coverage on [CircleCI](https://app.circleci.com/pipelines/github/ESMValGroup/ESMValCore) (open the `tests` job and click the ARTIFACTS tab). To see some of the results on CircleCI or Codecov, you may need to log in; you can do so using your GitHub account. When reviewing a pull request, always check that new code is covered by unit tests and [codecov](https://app.codecov.io/gh/ESMValGroup/ESMValCore/pulls) reports an increased coverage. ### Sample data New or modified preprocessor functions should preferably also be tested using the sample data. These tests are located in [tests/sample_data](https://github.com/ESMValGroup/ESMValCore/tree/main/tests/sample_data). Please mark new tests that use the sample data with the [decorator](https://docs.python.org/3/glossary.html#term-decorator) `@pytest.mark.use_sample_data`. The [ESMValTool_sample_data](https://github.com/ESMValGroup/ESMValTool_sample_data) repository contains samples of CMIP6 data for testing ESMValCore. The [ESMValTool-sample-data](https://pypi.org/project/ESMValTool-sample-data/) package is installed as part of the developer dependencies. The size of the package is relatively small (~ 100 MB), so it can be easily downloaded and distributed. Preprocessing the sample data can be time-consuming, so some intermediate results are cached by pytest to make the tests run faster. If you suspect the tests are failing because the cache is invalid, clear it by running ```bash pytest --cache-clear ``` To avoid running the time consuming tests that use sample data altogether, run ```bash pytest -m "not use_sample_data" ``` ### Automated testing Whenever you make a pull request or push new commits to an existing pull request, the tests in the `tests` of the branch associated with the pull request will be run automatically on [CircleCI](https://app.circleci.com/pipelines/github/ESMValGroup/ESMValCore). Every night, more extensive tests are run to make sure that problems with the installation of the tool are discovered by the development team before users encounter them. These nightly tests have been designed to follow the installation procedures described in the documentation, e.g. in the [Installation](quickstart/install.html.md#install) chapter. The nightly tests are run using both CircleCI and GitHub Actions. The result of the tests ran by CircleCI can be seen on the [CircleCI project page](https://app.circleci.com/pipelines/github/ESMValGroup/ESMValCore?branch=main) and the result of the tests ran by GitHub Actions can be viewed on the [Actions tab](https://github.com/ESMValGroup/ESMValCore/actions) of the repository (to learn more about the Github-hosted runners, please have a look the [documentation](https://docs.github.com/en/actions/using-github-hosted-runners)). The configuration of the tests run by CircleCI can be found in the directory [.circleci](https://github.com/ESMValGroup/ESMValCore/blob/main/.circleci), while the configuration of the tests run by GitHub Actions can be found in the directory [.github/workflows](https://github.com/ESMValGroup/ESMValCore/blob/main/.github/workflows). ## Backward compatibility The ESMValCore package is used by many people to run their recipes. Many of these recipes are maintained in the public [ESMValTool](https://github.com/ESMValGroup/ESMValTool) repository, but there are also users who choose not to share their work there. While our commitment is first and foremost to users who do share their recipes in the ESMValTool repository, we still try to be nice to all of the ESMValCore users. #### NOTE The [backward compatibility policy](https://docs.esmvaltool.org/en/latest/community/backward_compatibility.html#backward-compatibility-policy) outlines the key principles on backward compatibility and additional guidance on handling *backward-incompatible changes*. This policy applies to both, ESMValCore and ESMValTool. When making changes, e.g. to the [recipe format](recipe/overview.html.md#recipe-overview), the [diagnostic script interface](interfaces.html.md#interfaces), the public [Python API](api/esmvalcore.html.md#api), or the [configuration format](quickstart/configure.html.md#config), keep in mind that this may affect many users. To keep the tool user friendly, try to avoid making changes that are not backward compatible, i.e. changes that require users to change their existing recipes, diagnostics, configuration files, or scripts. If you really must change the public interfaces of the tool, always discuss this with the [@ESMValGroup/esmvaltool-coreteam](https://github.com/orgs/ESMValGroup/teams/esmvaltool-coreteam). Try to deprecate the feature first by issuing an [`ESMValCoreDeprecationWarning`](api/esmvalcore.exceptions.html.md#esmvalcore.exceptions.ESMValCoreDeprecationWarning) using the [`warnings`](https://docs.python.org/3/library/warnings.html#module-warnings) module and schedule it for removal two [minor versions](https://semver.org/) from the upcoming release. For example, when you deprecate a feature in a pull request that will be included in version 2.5, that feature should be removed in version 2.7: ```python import warnings from esmvalcore.exceptions import ESMValCoreDeprecationWarning # Other code def func(x, deprecated_option=None): """Deprecate deprecated_option.""" if deprecated_option is not None: deprecation_msg = ( "The option ``deprecated_option`` has been deprecated in " "ESMValCore version 2.5 and is scheduled for removal in " "version 2.7. Add additional text (e.g., description of " "alternatives) here.") warnings.warn(deprecation_msg, ESMValCoreDeprecationWarning, stacklevel=2) # Other code ``` Mention the version in which the feature will be removed in the deprecation message. Label the pull request with the [deprecated feature](https://github.com/ESMValGroup/ESMValCore/labels/deprecated%20feature) label. When deprecating a feature, please follow up by actually removing the feature in due course. If you must make backward incompatible changes, you need to update the available recipes in ESMValTool and link the ESMValTool pull request(s) in the ESMValCore pull request description. You can ask the [@ESMValGroup/esmvaltool-recipe-maintainers](https://github.com/orgs/ESMValGroup/teams/esmvaltool-recipe-maintainers) for help with updating existing recipes, but please be considerate of their time. You should tag the [@ESMValGroup/esmvaltool-coreteam](https://github.com/orgs/ESMValGroup/teams/esmvaltool-coreteam) to notify them of the backward-incompatible change, and give at least 2 weeks for objections to be raised before merging to the main branch. If a strong objection is raised the backwards-incompatible change should not be merged until the objection is resolved. When reviewing a pull request, always check for backward incompatible changes and make sure they are needed and have been discussed with the [@ESMValGroup/esmvaltool-coreteam](https://github.com/orgs/ESMValGroup/teams/esmvaltool-coreteam). Also, make sure the author of the pull request has created the accompanying pull request(s) to update the ESMValTool, before merging the ESMValCore pull request. ## Dependencies We follow the guidelines set out in [SPEC-0](https://scientific-python.org/specs/spec-0000/) regarding the supported Python versions and dependencies. Before considering adding a new dependency, carefully check that the [license](https://the-turing-way.netlify.app/reproducible-research/licensing/licensing-software.html) of the dependency you want to add and any of its dependencies are [compatible](https://the-turing-way.netlify.app/reproducible-research/licensing/licensing-compatibility.html) with the [Apache 2.0](https://github.com/ESMValGroup/ESMValCore/blob/main/LICENSE/) license that applies to the ESMValCore. Note that GPL version 2 license is considered incompatible with the Apache 2.0 license, while the compatibility of GPL version 3 license with the Apache 2.0 license is questionable. See this [statement](https://www.apache.org/licenses/GPL-compatibility.html) by the authors of the Apache 2.0 license for more information. When adding or removing dependencies, please consider applying the changes in the following locations in `pyproject.toml`: - `dependencies` contains dependencies that can be installed from [PyPI](https://pypi.org/) - `[tool.pixi.dependencies]` contains dependencies that can be installed from [conda-forge](https://conda-forge.org/) it is strongly preferred that those two lists are kept in sync, apart from differences in how packages are named. Run the command `pixi lock` after making changes to the dependencies to update the `pixi.lock` file, which is used to make sure that the same versions of packages are installed for all ESMValCore developers. There are also three feature groups for development dependencies: - `[tool.pixi.feature.dev]` contains tools that are useful for development - `[tool.pixi.feature.doc]` contains tools that are needed to build the documentation - `[tool.pixi.feature.test]` contains tools that are needed to run the tests #### TIP When reviewing a pull request where dependencies are added or removed, always check that the changes have been applied to both the PyPI and the conda-forge dependencies and that the `pixi.lock` file has been updated by running `pixi lock` after the changes were made. ## List of authors If you make a contribution to ESMValCore and you would like to be listed as an author (e.g. on [Zenodo](https://zenodo.org/record/4525749)), please add your name to the list of authors in `CITATION.cff` and generate the entry for the `.zenodo.json` file by running the commands ```default pip install cffconvert cffconvert --ignore-suspect-keys --outputformat zenodo --outfile .zenodo.json ``` Presently, this method unfortunately discards entries communities and grants from that file; please restore them manually, or alternately proceed with the addition manually ## Pull request checks To check that a pull request is up to standard, several automatic checks are run when you make a pull request. Read more about it in the [Tests]() and [Documentation]() sections. Successful checks have a green ✓ in front, a ❌ means the check failed. If you need help with the checks, please ask the technical reviewer of your pull request for help. Ask [@ESMValGroup/tech-reviewers](https://github.com/orgs/ESMValGroup/teams/tech-reviewers) if you do not have a technical reviewer yet. If the checks are broken because of something unrelated to the current pull request, please check if there is an open issue that reports the problem. Create one if there is no issue yet. You can attract the attention of the [@ESMValGroup/esmvaltool-coreteam](https://github.com/orgs/ESMValGroup/teams/esmvaltool-coreteam) by mentioning them in the issue if it looks like no-one is working on solving the problem yet. The issue needs to be fixed in a separate pull request first. After that has been merged into the `main` branch and all checks on this branch are green again, merge it into your own branch to get the tests to pass. When reviewing a pull request, always make sure that all checks were successful. See the section on [code_quality]() for more information. Never merge a pull request with failing pre-commit, CircleCI, or readthedocs checks.