Add docs

Author: coretl

.pre-commit-config.yaml

@@ -27,9 +27,9 @@ repos:
         require_serial: true
 
       # Make sure lock file satisfies dependencies in pyproject.toml.
-      - id: uv-lock
-        name: update uv.lock
+      - id: uv-sync
+        name: update uv.lock and venv
         pass_filenames: false
         language: system
-        entry: uv lock
+        entry: uv sync
         files: ^(uv\.lock|pyproject\.toml)$

README.md

@@ -44,7 +44,7 @@ git init --initial-branch=main /path/to/my-project
 copier copy https://github.com/DiamondLightSource/python-copier-template.git $_
 ```
 
-You can also use it via `pipx run copier` if you have that installed.
+You can also use it via `uvx copier` if you have `uv` installed.
 
 <!-- README only content. Anything below this line won't be included in index.md -->
 

docs/explanations/decisions/0023-uv.md

@@ -0,0 +1,23 @@
+# 23. Adopt uv
+
+Date: 2025-09-22
+
+## Status
+
+Accepted
+
+## Context
+
+[`uv`](https://docs.astral.sh/uv/) appears to be gaining a critical mass of adoption, and adopting the project flow would bring some benefits:
+- Much faster venv creation times
+- A native lockfile implementation
+- A single base image that can install multiple pythons
+- Which would allow us to make a single devcontainer base with our feature built in, which would speed up the devcontainer creation time
+
+## Decision
+
+We will adopt this flow.
+
+## Consequences
+
+Docs will need to be updated, especially around lockfile support. Commands will need to be updated slightly for the new version of tox. Work on `renovate` will need to follow as `dependabot` does not support the uv lockfile.

docs/how-to/lint.md

@@ -10,14 +10,14 @@ You can run the above checks on all files with this command:
 $ tox -e pre-commit
 ```
 
-Or you can install a pre-commit hook that will run each time you do a `git commit` on just the files that have changed:
+The devcontainer will also install a pre-commit hook that will run each time you do a `git commit` on just the files that have changed.
+
+If you want to commit with a failing pre-commit check then you have to:
 
 ```
-$ pre-commit install
+$ git commit --no-verify
 ```
 
-It is also possible to [automatically enable pre-commit on cloned repositories](https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories). This will result in pre-commits being enabled on every repo your user clones from now on.
-
 ## Fixing issues
 
 The typical workflow is:

docs/how-to/lock-requirements.md

@@ -2,48 +2,33 @@
 
 ## Introduction
 
-By design this project only defines dependencies in one place, i.e. in the `requires` table in `pyproject.toml`.
+Since the move to `uv`, this project natively supports a lockfile. This is a set of "known good" dependencies that the tests are run against, and will be used to create a container if one is built.
 
-In the `requires` table it is possible to pin versions of some dependencies as needed. For library projects it is best to leave  pinning to a minimum so that your library can be used by the widest range of applications.
+## Specifying dependencies
 
-When CI builds the project it will use the latest compatible set of dependencies available (after applying your pins and any dependencies' pins).
+The source of dependencies is the project's `pyproject.toml`. They can come from:
+- Project dependencies (from `[project]` `dependencies =`)
+- Dev dependencies (from `[dependency-groups]` `dev =`)
+- Transitive dependencies (child dependencies of the above)
 
-This approach means that there is a possibility that a future build may break because an updated release of a dependency has made a breaking change.
-
-The correct way to fix such an issue is to work out the minimum pinning in `requires` that will resolve the problem. However this can be quite hard to do and may be time consuming when simply trying to release a minor update.
-
-For this reason we provide a mechanism for locking all dependencies to the same version as a previous successful release. This is a quick fix that should guarantee a successful CI build.
-
-## Finding the lock files
-
-Every release of the project will have a set of requirements files published as release assets.
-
-For example take a look at the release page for python-copier-template [here](https://github.com/DiamondLightSource/python-copier-template/releases/tag/1.1.0)
-
-There is a single `dev-requirements.txt` file showing as an asset on the release. This has been created using `pip freeze --exclude-editable` on a successful test run using the same version of python as the devcontainer, and will contain a full list of the dependencies and sub-dependencies with pinned versions. You can download this file by clicking on it.
-
-## Applying the lock file
-
-To apply a lockfile:
-
-- copy the requirements file you have downloaded to the root of your repository
-- commit it into the repo
-- push the changes
-
-The CI looks for a `dev-requirements.txt` in the root and will pass it to pip as a constraint when installing the dev environment. If a package is required to be installed by `pyproject.toml` then `pip` will use the version specified in `dev-requirements.txt`.
+Dependencies are loosely specified in `pyproject.toml`, like `sphinx-autobuild` or `pydata-sphinx-theme>=0.12`. They should state a minimum version if you are using features that are added in a specific version. There should be no upper bound by default, only insert one if an upstream release of a dependency breaks your code, and you don't have time to fix it immediately.
 
 ## Updating the lockfile
 
-1. Open the repo in a devcontainer
-1. Delete dev-requirements.txt
-1. Restart your dev container
-1. Check the tests run
-1. Then run `pip freeze --exclude-editable > dev-requirements.txt`
-1. Check the new file into Git
-1. Push and merge the changes
+When you have updated `pyproject.toml` then run:
+```
+$ uv sync
+```
+
+This will ensure that any new dependencies you add will be placed in the lockfile, and your venv updated to match. It will *not* update any existing dependencies, unless `pyproject.toml` requires a later version.
 
-## Removing dependency locking from CI
+This command will be run by [pre-commit](./lint) during a `git commit` and by CI.
 
-Once the reasons for locking the build have been resolved it is a good idea to go back to an unlocked build. This is because you get an early indication of any incoming problems.
+To update all dependencies to their latest versions run:
+```
+uv sync --upgrade
+```
 
-To restore unlocked builds in CI simply remove `dev-requirements.txt` from the root of the repo and push.
+```{seealso}
+[The uv docs on locking and syncing](https://docs.astral.sh/uv/concepts/projects/sync)
+```

docs/how-to/update-template.md

@@ -26,7 +26,7 @@ The following steps are recommended to update your project, especially for infre
     - for devcontainers
         - `ctrl+shift+p` -> `Remote-Containers: Rebuild Without Cache and Reopen in Container`
     - for local development
-        - `pip install -e .[dev] --force-reinstall`
+        - `uv sync`
 - validate your project against the latest tools
     - `tox -p`
 - fix issues found by the above