Skip to content

chore: scaffold library with devcontainer, tooling and CI - #1

Merged
kristoflemmens merged 10 commits into
mainfrom
chore/scaffold
Oct 24, 2026
Merged

kristoflemmens merged 10 commits into
mainfrom
chore/scaffold

Conversation

@kristoflemmens

@kristoflemmens kristoflemmens commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

What and why

Sets up the repository skeleton agreed in the design session, so every later change can follow the TDD + PR workflow.

Development environment

  • .devcontainer/: Python 3.13 image with a pinned uv (0.13.5), a named volume for the uv cache, and postCreateCommand that syncs the environment and installs the prek hooks.
  • pyproject.toml: hatchling, src layout, modbus-connection>=4.12.6,<5 (with a tmodbus extra), ruff with ALL rules, mypy strict, pytest with a 100% line + branch coverage gate.
  • .pre-commit-config.yaml (run by prek): ruff check/format, uv-lock, mypy.

GitHub automation

  • ci.yml: lint/type-check, tests on 3.12/3.13/3.14, build, dependency review (PRs only), plus one aggregate CI success job — the required status check.

  • pr-title.yml: Conventional Commits PR titles (they drive release-please).

  • CodeQL via GitHub default setup (enabled after merge, no workflow file); dependabot.yml (uv, actions, Dockerfile, devcontainer).

  • release.yml: release-please → build → TestPyPI → PyPI via trusted publishing. All actions pinned by SHA.

  • Issue forms (bug, feature, register/firmware), PR template with TDD checklist, CODEOWNERS.

  • scorecard.yml: weekly OpenSSF Scorecard run on main, results in the Security tab and the README badge.

  • Devcontainer images pinned by digest; uv pinned once via [tool.uv] required-version (used by setup-uv, the Dockerfile tag matches).

Docs

  • docs/design.md (living design, no ADRs), CONTEXT.md (domain terms), docs/errata.md.
  • docs/protocol/17.1/: markdown transcription of the Thermia protocol with attribution; the PDF/DOCX are not redistributed, and the sdist on PyPI contains only src/ (no protocol text, no tests).
  • README badges: CI, PyPI, Python versions, OpenSSF Scorecard, license, coverage, uv, Ruff, mypy, Conventional Commits (PyPI badges show "not found" until the first publish).
  • AGENTS.md / CLAUDE.md with the red-green-refactor workflow.

Code

  • thermia_genesis.__version__, driven by the first test (tests/test_package.py), written red-first.

Setup status outside this PR

  • Release app: release.yml authenticates release-please with the org-wide klconsultancy-release-bot (org variable RELEASE_APP_CLIENT_ID, org secret RELEASE_APP_PRIVATE_KEY), so CI runs on release PRs.
  • main ruleset: PR required, squash only, linear history, CI success required, no force-push/deletion, no bypass.
  • Squash title = PR title, auto-delete branches, secret scanning + push protection, Dependabot alerts/security updates.
  • Trusted publishers on pypi.org / test.pypi.org and the pypi / testpypi environments.
  • release tags ruleset on v*: no create/update/delete except admins and the release app.
  • After merge: enable CodeQL default setup and add the code_scanning rule to the main ruleset.
  • Add Conventional commit title as a required check after merge (its pull_request_target workflow only runs once it is on main).

Release numbering: bump-minor-pre-major: true (a breaking change before 1.0 bumps the minor) and bump-patch-for-minor-pre-major is not set, so before 1.0 a feat: bumps the minor version; the first feature release is 0.1.0.

Checklist

  • The test was written first and failed for the right reason before the implementation
  • Coverage stays at 100%
  • docs/design.md / CONTEXT.md updated if a design choice or domain term changed
  • PR title follows Conventional Commits

🤖 Generated with Claude Code

Set up the python-thermia-genesis repository:

- devcontainer with Python 3.13 and a pinned uv
- hatchling package with src layout, ruff (ALL), mypy strict, pytest
  with a 100% line and branch coverage gate, prek hooks
- GitHub Actions: CI matrix (3.12-3.14), PR title check, CodeQL,
  dependency review, release-please with TestPyPI/PyPI trusted
  publishing; Dependabot; issue forms, PR template, CODEOWNERS
- docs/design.md, CONTEXT.md, errata and the 17.1 protocol transcription
- AGENTS.md/CLAUDE.md describing the TDD workflow

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-advanced-security

Copy link
Copy Markdown

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

  • The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
  • Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
  • You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.

kristoflemmens and others added 9 commits October 24, 2026 05:54
Allow the devcontainer exec forms of the dev commands, and deny
skipping hooks and pushing to main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Permissions live in the parent workspace folder Claude Code is started from.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Drop bump-patch-for-minor-pre-major so a feat commit releases 0.1.0
instead of 0.0.1. Authenticate release-please with the org-wide
klconsultancy-release-bot via its client id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dependency review now runs inside ci.yml so it gates the single required
'CI success' check. CodeQL moves to GitHub's default setup, enabled after
merge, so the advanced workflow is removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- run ruff from the lockfile in the hooks so hooks and CI agree
- pin uv via [tool.uv] required-version (setup-uv honours it)
- type-check against Python 3.12, the lowest supported version
- only cancel superseded CI runs on pull requests, never on main
- ship only the package in the sdist, not the Thermia protocol text
- depend on modbus-connection once; the dev group uses the tmodbus extra
- pin devcontainer images by digest, skip existing files on TestPyPI,
  drop the unneeded checkout and the empty devcontainers ecosystem

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Dependabot bumps the devcontainer image on its own; the pyproject
required-version and the uv-lock hook must follow in the same PR.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kristoflemmens
kristoflemmens merged commit 316d7a5 into main Oct 24, 2026
7 checks passed
@kristoflemmens
kristoflemmens deleted the chore/scaffold branch October 24, 2026 07:33
@kristoflemmens kristoflemmens mentioned this pull request Oct 24, 2026
4 tasks done
kristoflemmens added a commit that referenced this pull request Oct 24, 2026
## What and why

All changes are made in git worktrees under `.worktrees/<branch>`
instead of the main checkout. This PR makes the repository and
devcontainer work that way, as agreed after #1 (and covers the deferred
review points from #1).

- **Own venv per worktree**: `UV_PROJECT_ENVIRONMENT` is removed, so uv
creates `.venv` inside each worktree. Parallel worktrees no longer
overwrite each other's editable install. VS Code's default interpreter
now points at `${containerWorkspaceFolder}/.venv`.
- **Git in the devcontainer**: `postCreateCommand` also trusts
`${containerWorkspaceFolder}/.worktrees/*` as `safe.directory`. Combined
with `worktree.useRelativePaths` (set once per clone, documented),
worktree `.git` files resolve inside the container.
- **Ignore**: `.worktrees/` in `.gitignore` and in ruff's
`extend-exclude`.
- **Lint job on Python 3.14**, the same as the devcontainer since #2.
ruff and mypy keep checking against 3.12.
- **Docs**: the worktree workflow in `AGENTS.md` (commands), `README.md`
(development) and `docs/design.md` (process).

## Verified locally

Rebuilt the devcontainer from this branch's config (Python 3.14.8, uv
0.13.5). From the worktree: `git status` works in the container, `uv run
--directory .worktrees/worktree-workflow pytest` passes with 100%
coverage, all prek hooks pass, and the main checkout and the worktree
each have their own `.venv`.

## Checklist

- [x] The test was written first and failed for the right reason before
the implementation (no production code changed)
- [x] Coverage stays at 100%
- [x] `docs/design.md` / `CONTEXT.md` updated if a design choice or
domain term changed
- [x] PR title follows Conventional Commits

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants