Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 3 additions & 4 deletions .devcontainer/devcontainer.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand All @@ -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]": {
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
__pycache__/
*.py[cod]
.venv/
.worktrees/
build/
dist/
*.egg-info/
Expand Down
35 changes: 28 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,24 +10,45 @@ 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
the same PR. Do not create ADRs.

## 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/<branch> -b <branch> origin/main
```

Run the tools inside the devcontainer, from the worktree:

```sh
devcontainer exec --workspace-folder . uv run --directory .worktrees/<branch> 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/<branch>`.

## Registers

- Chapter 3 of `docs/protocol/17.1/03-address-list.md` is the source of truth. Use the
Expand Down
8 changes: 6 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<branch>`, 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`.
1 change: 1 addition & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ include = ["src"]
target-version = "py312"
line-length = 100
src = ["src", "tests"]
extend-exclude = [".worktrees"]

[tool.ruff.lint]
select = ["ALL"]
Expand Down
Loading