From b47acad0a9028601f80f846f0dabedd3509977bd Mon Sep 17 00:00:00 2001 From: Kristof Lemmens Date: Sat, 24 Oct 2026 13:41:01 +0000 Subject: [PATCH] chore: support working in git worktrees - give every worktree its own .venv (drop UV_PROJECT_ENVIRONMENT) - trust .worktrees/* as git safe.directory in the devcontainer - ignore .worktrees/ in git and ruff - run the lint job on Python 3.14, like the devcontainer - document the worktree workflow in AGENTS.md, README and design.md Co-Authored-By: Claude Opus 5.5 --- .devcontainer/devcontainer.json | 7 +++---- .github/workflows/ci.yml | 2 +- .gitignore | 1 + AGENTS.md | 35 ++++++++++++++++++++++++++------- README.md | 8 ++++++-- docs/design.md | 3 +++ pyproject.toml | 1 + 7 files changed, 43 insertions(+), 14 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 111339b..5abde39 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -4,13 +4,12 @@ "dockerfile": "Dockerfile" }, "containerEnv": { - "UV_LINK_MODE": "copy", - "UV_PROJECT_ENVIRONMENT": "/home/vscode/.venv" + "UV_LINK_MODE": "copy" }, "mounts": [ "source=thermia-genesis-uv-cache,target=/home/vscode/.cache/uv,type=volume" ], - "postCreateCommand": "git config --global --add safe.directory ${containerWorkspaceFolder} && uv sync && uv run prek install --overwrite", + "postCreateCommand": "git config --global --add safe.directory ${containerWorkspaceFolder} && git config --global --add safe.directory '${containerWorkspaceFolder}/.worktrees/*' && uv sync && uv run prek install --overwrite", "customizations": { "vscode": { "extensions": [ @@ -24,7 +23,7 @@ "github.vscode-pull-request-github" ], "settings": { - "python.defaultInterpreterPath": "/home/vscode/.venv/bin/python", + "python.defaultInterpreterPath": "${containerWorkspaceFolder}/.venv/bin/python", "python.testing.pytestEnabled": true, "editor.formatOnSave": true, "[python]": { diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1f0eec7..ebf1287 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -35,7 +35,7 @@ jobs: fi - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2 with: - python-version: "3.13" + python-version: "3.14" # same as the devcontainer - run: uv sync --locked - run: uv run ruff format --check - run: uv run ruff check --output-format=github diff --git a/.gitignore b/.gitignore index 80dd81e..2f49a52 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ __pycache__/ *.py[cod] .venv/ +.worktrees/ build/ dist/ *.egg-info/ diff --git a/AGENTS.md b/AGENTS.md index b72b705..b8cd361 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,8 @@ terms before changing code. then write the minimum code to pass, then refactor. Never write production code without a failing test that requires it. - Coverage must stay at 100% (line and branch); CI fails otherwise. -- Work on a branch and open a pull request. Never push to `main`. +- Work in a worktree on a branch and open a pull request. Never edit the main checkout and + never push to `main` (see Commands). - PR titles and squash commits follow Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `build:`, `ci:`, `chore:`). They drive release-please. - When a design choice or domain term changes, update `docs/design.md` or `CONTEXT.md` in @@ -18,16 +19,36 @@ terms before changing code. ## Commands -Run inside the devcontainer: +Once per clone, on the host: ```sh -uv run pytest # tests + coverage gate -uv run ruff format # format -uv run ruff check # lint -uv run mypy # type-check (strict) -uv run prek run -a # all pre-commit hooks +git config worktree.useRelativePaths true ``` +Start a change in a new worktree (on the host): + +```sh +git fetch origin +git worktree add .worktrees/ -b origin/main +``` + +Run the tools inside the devcontainer, from the worktree: + +```sh +devcontainer exec --workspace-folder . uv run --directory .worktrees/ pytest +``` + +| Command | Purpose | +| ---------------------- | --------------------------- | +| `uv run pytest` | tests + coverage gate | +| `uv run ruff format` | format | +| `uv run ruff check` | lint | +| `uv run mypy` | type-check (strict) | +| `uv run prek run -a` | all pre-commit hooks | + +Commit inside the devcontainer so the hooks run, push from the host, and remove the worktree +after the merge with `git worktree remove .worktrees/`. + ## Registers - Chapter 3 of `docs/protocol/17.1/03-address-list.md` is the source of truth. Use the diff --git a/README.md b/README.md index ea1ef5a..1c0aa6a 100644 --- a/README.md +++ b/README.md @@ -27,10 +27,14 @@ pip install "thermia-genesis[tmodbus]" ## Development -Open the repository in its devcontainer, then: +Changes are made in git worktrees under `.worktrees/`, and the tools run in the +repository's devcontainer: ```sh -uv run pytest +git config worktree.useRelativePaths true +git worktree add .worktrees/my-change -b my-change origin/main +devcontainer up --workspace-folder . +devcontainer exec --workspace-folder . uv run --directory .worktrees/my-change pytest ``` See [`AGENTS.md`](AGENTS.md) for the workflow and [`docs/design.md`](docs/design.md) for the diff --git a/docs/design.md b/docs/design.md index be93da9..fb5ab13 100644 --- a/docs/design.md +++ b/docs/design.md @@ -83,3 +83,6 @@ possible. `async_update()` returns an `UpdateReport` so callers can tell which p turns merged commits into a release PR; merging it tags `vX.Y.Z`, creates a GitHub Release and publishes to TestPyPI and then PyPI via trusted publishing. - Development happens in the devcontainer; nothing has to be installed on the host. +- Every change is made in a git worktree under `.worktrees/`, never in the main + checkout. Worktrees use relative paths (`worktree.useRelativePaths`) so they also work + inside the devcontainer, and each worktree has its own `.venv`. diff --git a/pyproject.toml b/pyproject.toml index 40a028e..593b9ac 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -55,6 +55,7 @@ include = ["src"] target-version = "py312" line-length = 100 src = ["src", "tests"] +extend-exclude = [".worktrees"] [tool.ruff.lint] select = ["ALL"]