Developer’s Guide¶

To aid in the development of CSET we are adopting some working practices so everyone involved knows what to expect. Linked from this page is everything you need to get started, and the links below go into more detail on specific topics.

Contributing checklist¶

If you have just opened a pull request (PR), then these are the things you need to do ahead of a code review.

Documentation has been updated to reflect change¶

If you’ve added a new function check whether it has been documented? If you changed the name of a setting have you changed it everywhere in the documentation?

New code has tests, and affected old tests have been updated¶

A comment should be automatically posted on your PR showing how much of your code is tested. Try and keep this as high as possible by adding new tests when you add new code. Also, make sure the tests are actually testing a reasonable range of different uses. For more, see Automatic Testing.

All tests and CI lints pass¶

All of the pre-existing tests should pass, as should the formatting and linting checks. If they are not, click on “Details” next to the failing check and it will show you what failed. Some of the errors are auto-corrected. In that case you need to add the file again with git add and rerun the commit.

Pull request checks, with a couple failing. The details link is highlighted.

Added an entry to the top of `docs/source/changelog.rst`¶

For any non-trivial change an entry in the Changelog should be created. Put a line describing your change in the Unreleased section at the top of the file. Take inspiration from the other entries, and link to your PR using the :pr:`123` directive. If this is your first time contributing also link your GitHub username to your profile by adding the following line in that section:

.. _@username: https://github.com/username

Conda lock files have been updated if dependencies changed¶

If you have changed the dependencies of CSET you will need to regenerate the conda dependency lock files. This can be done by running the update conda lock files workflow from your branch, then merging the PR it creates into your own branch. (Not the default main branch!)

Said whether Generative AI, such as GitHub Copilot, has been used in this PR¶

Generative AI tools such as GitHub Copilot are useful, but there are still unanswered questions around the copyright of their output. Therefore CSET contributions that used Generative AI must disclose it, along with the name of the AI tool used. This can be a simple statement in the PR description, for example:

This PR contains AI generated code from GitHub Copilot.

Marked the PR as ready to review¶

Green status symbol indicating an open PR ready for review.

If you opened the PR as a draft make sure it is marked as ready for review with a green status symbol when you want others to look at it.