From 0bc4797e6d49051f158c3764b38dcd0466747210 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Wed, 28 Aug 2024 14:44:40 -0700 Subject: [PATCH] Document the new dependency method Add documentation to the developer guide on how to update dependencies, and give an example of how to point Safir to a Git dependency. --- docs/dev/development.rst | 32 ++++++++++++++++++++++++++++++++ requirements/main.in | 40 ---------------------------------------- 2 files changed, 32 insertions(+), 40 deletions(-) delete mode 100644 requirements/main.in diff --git a/docs/dev/development.rst b/docs/dev/development.rst index f7c83d6e8..cbd80861c 100644 --- a/docs/dev/development.rst +++ b/docs/dev/development.rst @@ -188,6 +188,38 @@ Slashes will be replaced with underscores. By default, this means the branch name must begin with ``tickets/``. You can change this in :file:`.github/workflows/ci.yaml` under the ``build`` step. +Updating dependencies +===================== + +Runtime Python dependencies for Gafaelfawr are recorded in :file:`pyproject.toml` like a regular Python package. +Development dependencies are separately recorded in :file:`requirements/dev.in`. +Dependencies needed to run :command:`tox` are recorded in :file:`requirements/tox.in`. + +After changing any of those files, run :command:`make update-deps` to rebuild the frozen dependency files in :file:`requirements/*.txt`. +Those frozen dependency files are used to build the release Docker image, and are used as the dependencies in tox environments for testing, documentation builds, and other checks. + +:command:`make update-deps` should also be run as part of the release process to update frozen dependencies to their latest versions. + +Temporary Git dependencies +-------------------------- + +By default, :command:`make update-deps` records the hashes of all dependencies. +It therefore cannot be used for Git dependencies, which are sometimes convenient during development. +If you need to depend on, for example, a Git version of Safir, change the ``safir`` dependency in :file:`pyproject.toml` to something like: + +.. code-block:: toml + + dependencies = [ + # ... + "safir[db,kubernetes] @ git+https://github.com/lsst-sqre/safir@main#subdirectory=safir", + # ... + ] + +Then, run :command:`make update-deps-no-hashes` instead to generate frozen dependencies without the hashes. + +Do not release new non-alpha versions of Gafaelfawr with Git dependencies. +The other package should be released first before a new version of Gafaelfawr is released. + .. _db-migrations: Creating database migrations diff --git a/requirements/main.in b/requirements/main.in deleted file mode 100644 index 5ddcb6f5b..000000000 --- a/requirements/main.in +++ /dev/null @@ -1,40 +0,0 @@ -# Editable runtime dependencies (equivalent to install_requires) -# Add direct runtime dependencies here, as well as implicit dependencies -# with constrained versions. -# -# After editing, update requirements/main.txt by running: -# make update-deps - -# These dependencies are for fastapi including some optional features. -fastapi -python-multipart -starlette -uvicorn[standard] - -# Other dependencies. -alembic[tz] -asyncpg -bonsai>=1.5.0 -cachetools -click>8.1.4 -cryptography -google-cloud-firestore -httpx -kopf -kubernetes_asyncio -jinja2 -opentelemetry-api -opentelemetry-exporter-otlp-proto-grpc -opentelemetry-sdk -pydantic>2 -pydantic-settings -PyJWT -pyyaml -redis>=4.2.0 -safir[db,kubernetes]>=6.2.0 -sqlalchemy -structlog - -# Uncomment this, change the branch, comment out safir above, and run make -# update-deps-no-hashes to test against an unreleased version of Safir. -# safir[db,kubernetes] @ git+https://github.com/lsst-sqre/safir@main