Skip to content

docs: bring template ADRs to living-schema conformance #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NWarila merged 1 commit into from
Jun 3, 2026
Merged

docs: bring template ADRs to living-schema conformance #35

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
23 changes: 0 additions & 23 deletions docs/README.md
View file
Open in desktop

This file was deleted.

47 changes: 31 additions & 16 deletions docs/decision-records/template/0001-scripts-are-standalone-and-stdlib-only.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,20 @@
# ADR-0001: QA Scripts Are Standalone and Stdlib-Only

| Field | Value |
| -------------- | --------------------------------------- |
| Status | Accepted |
| Date | 2026-04-08 |
| Authors | Nick Warila (@NWarila) |
| Decision-maker | Nick Warila (sole portfolio maintainer) |
| Consulted | Python packaging and tooling docs. |
| Informed | Downstream Python repositories. |
| Reversibility | Medium |
| Review-by | N/A (Accepted) |
| Field | Value |
| ---------------- | ---------------------------------------------------------------------------- |
| ID | ADR-0001 |
| Scope | Template |
| Status | Accepted |
| Decision-subject | QA scripts are standalone, stdlib-only, and independently syncable. |
| Date accepted | 2026-04-08 |
| Date | 2026-06-03 |
| Last reviewed | 2026-06-03 |
| Authors | Nick Warila (@NWarila) |
| Decision-makers | Nick Warila (sole portfolio maintainer) |
| Consulted | Python packaging and tooling docs. |
| Informed | Downstream Python repositories. |
| Reversibility | Medium |
| Review-by | 2026-11-30 |

## TL;DR

Expand All @@ -33,15 +38,15 @@ Two design paths were considered:

## Considered Options

1. Standalone, stdlib-only scripts — no shared module, no third-party deps.
1. Standalone, stdlib-only scripts - no shared module, no third-party deps.
2. Shared helper module (`_common.py`) imported by each check script.
3. Template Python package installed as a dev dependency.

## Decision Outcome

Chosen option: **Option 1, standalone stdlib-only scripts.**

Each `check_*.py` file reads `pyproject.toml` via `tomllib` (stdlib since 3.11), resolves paths, invokes the tool via `subprocess`, and reports results — all inline. The `~10-line config-reading pattern is duplicated across scripts rather than shared.
Each `check_*.py` file reads `pyproject.toml` via `tomllib` (stdlib since 3.11), resolves paths, invokes the tool via `subprocess`, and reports results - all inline. The `~10-line` config-reading pattern is duplicated across scripts rather than shared.

Scripts shell out to the actual tools (`ruff`, `mypy`, `pytest`, `pip-audit`, `codespell`, `build`, `twine`) and do not import them. This means the scripts carry zero non-stdlib import dependencies of their own.

Expand Down Expand Up @@ -69,7 +74,7 @@ Scripts shell out to the actual tools (`ruff`, `mypy`, `pytest`, `pip-audit`, `c
## Confirmation

1. No `check_*.py` or `qa.py` file contains a cross-script import.
2. The only stdlib module used for config reading is `tomllib` (Python 3.11+), consistent with the org's minimum supported version (ADR-0003).
2. The only stdlib module used for config reading is `tomllib` (Python 3.11+), consistent with this template's minimum supported Python version ([ADR-0003](0003-python-minimum-version-floor.md)).
3. `mypy` and `ruff` pass on all scripts in CI (`template-ci.yml`).

## Consequences
Expand All @@ -89,7 +94,7 @@ Scripts shell out to the actual tools (`ruff`, `mypy`, `pytest`, `pip-audit`, `c

## Assumptions

1. Python 3.11 remains the minimum version for the org (see PLAN.md Resolved Decision 15).
1. Python 3.11 remains the minimum version for this template (see PLAN.md Resolved Decision 15).
2. The set of check scripts stays small enough that per-file duplication is manageable.

## Supersedes
Expand All @@ -107,5 +112,15 @@ None (current).

## Related ADRs

- ADR-0002: Pull-based manifest-driven template sync
- ADR-0003: Python minimum version floor
- [ADR-0002](0002-pull-based-manifest-driven-template-sync.md): Pull-based manifest-driven template sync.
- [ADR-0003](0003-python-minimum-version-floor.md): Python minimum version floor.

## Compliance Notes

None.

## Changelog

| Date | Change | Reason | Author/Role | Body-diff? |
| ---------- | --------------------------------------- | -------------------------------------------------- | ----------------------------------- | ---------- |
| 2026-06-03 | Reformatted to the living ADR schema. | Satisfy the template ADR conformance gate. | Portfolio maintainer / template ADR | Yes |
43 changes: 29 additions & 14 deletions docs/decision-records/template/0002-pull-based-manifest-driven-template-sync.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,20 @@
# ADR-0002: Pull-Based, Manifest-Driven Template Sync

| Field | Value |
| -------------- | --------------------------------------- |
| Status | Accepted |
| Date | 2026-04-08 |
| Authors | Nick Warila (@NWarila) |
| Decision-maker | Nick Warila (sole portfolio maintainer) |
| Consulted | GitHub Actions reusable workflow docs, git submodule docs. |
| Informed | Downstream Python repositories. |
| Reversibility | Medium |
| Review-by | N/A (Accepted) |
| Field | Value |
| ---------------- | ---------------------------------------------------------------------------- |
| ID | ADR-0002 |
| Scope | Template |
| Status | Accepted |
| Decision-subject | Template updates are synced by downstream-owned pull requests and manifests. |
| Date accepted | 2026-04-08 |
| Date | 2026-06-03 |
| Last reviewed | 2026-06-03 |
| Authors | Nick Warila (@NWarila) |
| Decision-makers | Nick Warila (sole portfolio maintainer) |
| Consulted | GitHub Actions reusable workflow docs, git submodule docs. |
| Informed | Downstream Python repositories. |
| Reversibility | Medium |
| Review-by | 2026-11-30 |

## TL;DR

Expand Down Expand Up @@ -59,7 +64,7 @@ The template publishes a GitHub release whenever `scripts/` changes (via `auto-r

- Good, because it uses native git tooling.
- Bad, because submodules pin to a commit, not a release; there is no selective file mapping.
- Bad, because downstream repos get no PR with migration notes — the submodule bump is one diff line.
- Bad, because downstream repos get no PR with migration notes - the submodule bump is one diff line.
- Bad, because submodule workflows are brittle across clone contexts.

### Option 3: Versioned Python package
Expand All @@ -81,7 +86,7 @@ The template publishes a GitHub release whenever `scripts/` changes (via `auto-r

1. `sync-manifest.json` at the repository root defines all synced source-to-destination mappings.
2. `self-update.yml` supports `workflow_call` so downstream repos can call it as a reusable workflow.
3. The reusable workflow uses `GITHUB_TOKEN` (downstream repo's own token) for PR creation — no PAT.
3. The reusable workflow uses `GITHUB_TOKEN` (downstream repo's own token) for PR creation - no PAT.
4. `auto-release.yml` creates a new release when `scripts/` changes merge to `main`.
5. This repo dogfoods the sync mechanism via a nightly scheduled run of `self-update.yml`.

Expand Down Expand Up @@ -121,5 +126,15 @@ None (current).

## Related ADRs

- ADR-0001: QA scripts are standalone and stdlib-only
- ADR-0004: Use Renovate for dependency updates (`.github/renovate.json5`)
- [ADR-0001](0001-scripts-are-standalone-and-stdlib-only.md): QA scripts are standalone and stdlib-only.
- [org ADR-0004 (Use Renovate for dependency updates)](../org/0004-use-renovate-for-dependency-updates.md): `.github/renovate.json5`.

## Compliance Notes

None.

## Changelog

| Date | Change | Reason | Author/Role | Body-diff? |
| ---------- | --------------------------------------- | -------------------------------------------------- | ----------------------------------- | ---------- |
| 2026-06-03 | Reformatted to the living ADR schema. | Satisfy the template ADR conformance gate. | Portfolio maintainer / template ADR | Yes |
130 changes: 130 additions & 0 deletions docs/decision-records/template/0003-python-minimum-version-floor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
# ADR-0003: Python Minimum Version Floor

| Field | Value |
| ---------------- | ---------------------------------------------------------------------------- |
| ID | ADR-0003 |
| Scope | Template |
| Status | Accepted |
| Decision-subject | The template requires Python 3.11 or newer. |
| Date accepted | 2026-06-03 |
| Date | 2026-06-03 |
| Last reviewed | 2026-06-03 |
| Authors | Nick Warila (@NWarila) |
| Decision-makers | Nick Warila (sole portfolio maintainer) |
| Consulted | Python packaging docs, CPython `tomllib` docs, Ruff configuration docs. |
| Informed | Downstream Python repositories. |
| Reversibility | Medium |
| Review-by | 2026-11-30 |

## TL;DR

This template requires Python 3.11 or newer. The floor is already encoded in `pyproject.toml` as `requires-python = ">=3.11"` and in Ruff as `target-version = "py311"`. It also makes the stdlib-only QA scripts in [ADR-0001](0001-scripts-are-standalone-and-stdlib-only.md) possible because they can use `tomllib` without a backport dependency.

## Context and Problem Statement

The template provides reusable quality-gate scripts, workflow files, and reference configuration for downstream Python repositories. Those scripts are intentionally standalone and stdlib-only per [ADR-0001](0001-scripts-are-standalone-and-stdlib-only.md), so they need a Python runtime whose standard library contains the parsing functionality they depend on.

`tomllib` entered the Python standard library in Python 3.11. The QA scripts read `pyproject.toml`, so supporting Python versions earlier than 3.11 would either require a non-stdlib TOML dependency, duplicate parser logic, or conditional compatibility code. Each option conflicts with the standalone script decision.

The repository already declares the same floor in `pyproject.toml`: `[project] requires-python = ">=3.11"`, `[tool.ruff] target-version = "py311"`, and `[tool.mypy] python_version = "3.11"`. The ADR records that those settings are intentional template policy, not accidental tool defaults.

## Decision Drivers

1. Keep the QA scripts stdlib-only and individually copyable.
2. Avoid compatibility shims or backport dependencies in template infrastructure.
3. Align package metadata, lint configuration, and type-checking configuration around one Python baseline.
4. Permit modern typing and standard-library APIs in future template code.
5. Keep downstream expectations explicit before they adopt or sync the template.

## Considered Options

1. Support Python 3.10 and newer with a TOML backport or compatibility path.
2. Require Python 3.11 and newer.
3. Require only the newest actively developed Python minor version.

## Decision Outcome

Chosen option: **Option 2, require Python 3.11 and newer.**

The template's Python floor is 3.11. `pyproject.toml` remains the machine-readable source for packaging and tool configuration, while this ADR records the rationale. The QA scripts may use `tomllib` directly and do not need a backport dependency or runtime fallback for older Python versions.

Future changes to the Python floor must update this ADR, `pyproject.toml`, and any affected QA-script assumptions together.

## Pros and Cons of the Options

### Option 1: Support Python 3.10 and newer

- Good, because it would let older downstream environments adopt the template without upgrading Python first.
- Bad, because `tomllib` is not available in the Python 3.10 standard library.
- Bad, because adding a TOML backport would violate the stdlib-only QA-script decision.
- Bad, because conditional compatibility code would make each standalone script harder to read and maintain.

### Option 2: Require Python 3.11 and newer

- Good, because it matches the existing `pyproject.toml` package metadata and Ruff target version.
- Good, because it allows direct `tomllib` use with no helper package.
- Good, because it supports modern typing and standard-library features without compatibility shims.
- Neutral, because downstream repositories must provide Python 3.11 or newer before adopting the template.
- Bad, because repositories pinned to older Python runtimes must upgrade or defer adoption.

### Option 3: Require only the newest actively developed Python minor version

- Good, because it would maximize access to current language and tooling features.
- Bad, because it would create unnecessary churn for downstream repositories.
- Bad, because the template does not currently need features beyond Python 3.11 to meet its QA-script contract.

## Confirmation

1. `pyproject.toml` declares `[project] requires-python = ">=3.11"`.
2. `pyproject.toml` declares `[tool.ruff] target-version = "py311"`.
3. `pyproject.toml` declares `[tool.mypy] python_version = "3.11"`.
4. QA scripts may import `tomllib` directly and must not add a TOML backport dependency for template-owned config reading.

## Consequences

### Positive

- The template has one clear Python baseline across packaging, linting, typing, and scripts.
- The stdlib-only script policy stays simple because `tomllib` is available.
- Future template code can use Python 3.11 typing and standard-library behavior without compatibility layers.

### Negative

- Downstream repositories on Python 3.10 or older cannot adopt the template unchanged.
- Lowering the floor later would require revisiting script imports, tool targets, and type syntax.

### Neutral

- The Python floor is a template-tier decision. Individual downstream repositories may choose a stricter floor, but they should not claim compatibility below the template floor while syncing these scripts unchanged.

## Assumptions

1. Downstream repositories that adopt this template can run CI and local QA with Python 3.11 or newer.
2. The template continues to value stdlib-only QA scripts over older runtime compatibility.
3. The template does not need to support Python interpreters outside the CPython-compatible packaging and tooling ecosystem.

## Supersedes

None.

## Superseded by

None (current).

## Implementing PRs

None yet. The policy is already reflected in `pyproject.toml`; future PRs that change the floor should be listed here.

## Related ADRs

- [ADR-0001](0001-scripts-are-standalone-and-stdlib-only.md): QA scripts are standalone and stdlib-only.

## Compliance Notes

None.

## Changelog

| Date | Change | Reason | Author/Role | Body-diff? |
| ---------- | ------------------------------------------- | -------------------------------------------------------- | ----------------------------------- | ---------- |
| 2026-06-03 | Accepted the template Python version floor. | Document the Python 3.11 policy already encoded in tools. | Portfolio maintainer / template ADR | Yes |
Loading
Loading