Merge pull request #1440 from MetOffice/776_document_adding_a_new_dependency

Document how to add new dependencies to CSET

Author: jfrost-mo

docs/source/contributing/dependencies.rst

@@ -0,0 +1,89 @@
+Dependencies
+============
+
+Requirements of a new dependency
+--------------------------------
+
+Dependencies should be sufficiently maintained before being added to CSET. This
+is typically observed through recent and regular activity on the source
+repository, especially from multiple people. The dependency should be adding a
+valuable capability to justify the potential cost of us having to maintain or
+replace it in future.
+
+Finally dependencies must be published under an open source licence that is
+compatible with CSET's, and be distributed via conda-forge.
+
+Adding a new dependency
+-----------------------
+
+While a single ``conda install <package>`` can be used to experiment with an
+additional dependency, to properly include it in CSET it needs to be added to a
+number of files.
+
+Specifically it needs to be added to the ``pyproject.toml`` under the
+"dependencies" key, and ``requirements/environment.yaml`` under the appropriate
+dependencies section.
+
+After updating those two files and making a pull request, you'll need to rerun
+the conda lockfile generation action. In `Actions > Update conda lock files >
+Run workflow`_ select your branch, then run the workflow. A new PR will be
+created to update the lockfiles, which you can merge into your own branch.
+
+.. _Actions > Update conda lock files > Run workflow: https://github.com/MetOffice/CSET/actions/workflows/conda-lock.yml
+
+Updating the conda-forge package
+--------------------------------
+
+Conda packages are built from "feedstocks", which are repositories that contain
+the list of steps to build, package, and test the package, as well as the
+required metadata, such as the package name, and needed dependencies.
+
+The CSET feedstock is at `github.com/conda-forge/cset-feedstock`_. The only user
+editable file in this repository is `recipe/recipe.yaml`_. All of the other
+files are either automatically generated from the recipe file, or are inert
+things that don't affect the resultant package, like the README.
+
+In this case we care about the runtime dependencies in `recipe/recipe.yaml`_:
+
+    `Lines 27 to 37 in commit 805148a`_:
+
+    .. code-block:: yaml
+
+        run:
+        - python >=${{ python_min }}
+        - numpy
+        - iris >=3.12.2
+        - ruamel.yaml >=0.17
+        - pygraphviz >=1.11
+        - mo_pack >=0.3
+        - isodate >=0.6
+        - markdown-it-py >=3.0
+        - nc-time-axis
+        - iris-grib
+
+Because this repository is not within the MetOffice GitHub organisation, we
+cannot directly change it. We have to make a `fork of the repository`_ to make
+changes. Once you have created a fork, you can edit the feedstock recipe and
+make the needed changes. In this case we need two changes.
+
+1. Add the new dependency under the runtime requirements section. Remember to
+   use the conda-forge package name!
+
+   .. code-block:: yaml
+
+       requirements:
+         run:
+           - my_dependency
+
+2. Increase the `build number`_. This is used when the package version does not
+   increase, so conda knows which version is more up-to-date.
+
+Finally make your pull request, the `feedstock maintainer`_ will review and merge
+it, and soon after your updated package will be published on conda-forge.
+
+.. _github.com/conda-forge/cset-feedstock: https://github.com/conda-forge/cset-feedstock
+.. _recipe/recipe.yaml: https://github.com/conda-forge/cset-feedstock/blob/main/recipe/recipe.yaml
+.. _Lines 27 to 37 in commit 805148a: https://github.com/conda-forge/cset-feedstock/blob/805148a2191e1256667fb74f8e5b051f6339af56/recipe/recipe.yaml#L27-L37
+.. _fork of the repository: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo
+.. _build number: https://github.com/conda-forge/cset-feedstock/blob/805148a2191e1256667fb74f8e5b051f6339af56/recipe/recipe.yaml#L14
+.. _feedstock maintainer: https://github.com/conda-forge/cset-feedstock?tab=readme-ov-file#feedstock-maintainers

docs/source/contributing/index.rst

@@ -13,6 +13,7 @@ need to get started, and the links below go into more detail on specific topics.
     testing
     documentation
     code-review
+    dependencies
     releases
 
 Contributing checklist