Skip to content

docs: correct the CI trigger description and state the supported Python range - #38

Merged
dmccoystephenson merged 2 commits into
mainfrom
feature/readme-ci-trigger-accuracy
Aug 11, 2026
Merged

docs: correct the CI trigger description and state the supported Python range#38
dmccoystephenson merged 2 commits into
mainfrom
feature/readme-ci-trigger-accuracy

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

A documentation accuracy sweep was run across README.md, RELEASING.md, pyproject.toml, the workflow files and the graphik.py docstrings, with every claim checked against the source it describes. One inaccuracy and one omission were found, both in the README, and both are corrected here.

  • The CI trigger was overstated. The Development section claimed .github/workflows/test.yml runs "on every push and pull request". The workflow is triggered by push: branches: [main] and pull_request, so a push to a feature branch with no open pull request is not covered. That gap is now stated plainly, since it is precisely the situation in which a contributor is most likely to assume CI has already run.
  • The same sentence undersold the workflow. A compile check and an import smoke test run before pytest, across the full support matrix, none of which was mentioned.
  • The supported interpreter range was documented nowhere. pyproject.toml pins requires-python = ">=3.9" and the matrix covers 3.9 through 3.13, but neither figure appeared in the README. Both are now stated next to the dependency list.

No code, test, packaging or workflow file is touched — the change is confined to README.md.

Deferred this cycle

  • release: version tags are pushed without the 'v' prefix publish.yml requires, so no release has ever been published #34 (release tags pushed without the v prefix) was left untouched. It is gated on a maintainer decision between two release-process directions, and it touches .github/workflows/ and the release procedure, both of which are excluded from autonomous change.
  • The header comment of .github/workflows/test.yml carries the same "every push and pull request" overstatement corrected here. It was left alone because workflow files are excluded from autonomous change; a separate issue has been filed so the two do not stay out of step.

Test plan

  • python3 -m py_compile src/main/python/preponderous/graphik/graphik.py — passes
  • python3 -c "import preponderous.graphik" import smoke test — passes, reports 0.3.0.dev20260808
  • python3 -m pytest -q (headless via conftest.py) — 37 passed
  • Every corrected claim was re-verified against .github/workflows/test.yml and pyproject.toml rather than from memory

No tracking issue — the drift was found during a documentation accuracy sweep.

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

…on range

The Development section claimed test.yml runs "on every push and pull
request". The workflow is triggered by `push: branches: [main]` and
`pull_request`, so a push to a feature branch with no open PR is not
covered -- worth saying plainly, since that is exactly the case where a
contributor is likely to assume CI has their back.

The same sentence also undersold the workflow: it runs a compile check and
an import smoke test before pytest, across a 3.9-3.13 matrix.

The supported interpreter range was documented nowhere in the README even
though pyproject.toml pins `requires-python = ">=3.9"`, so it is now stated
next to the dependency list.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Self-review finding: the new line repeated test.yml's rationale for stopping
at 3.13 (pygame's prebuilt wheel range), creating a second place that goes
stale the moment pygame ships a cp314 wheel. The README states the tested
range and defers the reason to the workflow that encodes it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric

Scored against the diff and command output rather than judgment. Items with no surface in this PR are marked N/A with the reason.

  • Scope: PASSgit diff --name-only origin/main...HEAD returns README.md alone. No code, test, packaging or workflow file is touched, and no unrelated formatting or reflowing was introduced.
  • Docs: FAIL, then fixed — the first revision restated test.yml's rationale for stopping at 3.13 ("the versions pygame ships prebuilt wheels for") in the README. That duplicates a claim about pygame's release artifacts into a second file, which goes stale the moment pygame ships a cp314 wheel — precisely the drift this sweep exists to remove. Corrected in 49263f5: the README now states the tested range and defers the reason to the workflow that encodes it. Re-scored PASS.
  • Docs, remaining gap: acknowledged, tracked.github/workflows/test.yml:1 still carries the same "every push and pull request" overstatement being corrected in the README, so the two files disagree until it is addressed. Workflow files are excluded from autonomous change, so it was filed as ci: test.yml's header comment claims it runs on every push, but pushes outside main are only covered via pull_request #39 rather than fixed here. Left visible rather than silent, since a partial correction that leaves the sibling wrong is worth flagging.
  • Claim verification: PASS — each corrected statement was checked against source, not memory. .github/workflows/test.yml declares on: push: branches: [main] and pull_request: (so a branch pushed without an open PR runs nothing), its steps are Install → Compile check → Import smoke test → Run tests in that order, and its matrix is ["3.9", "3.10", "3.11", "3.12", "3.13"]. pyproject.toml declares requires-python = ">=3.9".
  • manual validation: PASS — the anchor is green on the PR head: py_compile succeeds, python3 -c "import preponderous.graphik" reports 0.3.0.dev20260808, and python3 -m pytest -q reports 37 passed. Run on Python 3.8.10 locally, below the declared floor of 3.9; the workflow covers 3.9-3.13 on the pull request itself.
  • Backward-compat: PASS — no public member of Graphik is renamed, removed or resignatured; the diff contains no Python.
  • No new deps: PASS — the Dependencies list is unchanged at pygame, matching the only third-party import in graphik.py.
  • Version sync: PASS — no version string is changed, and the README carries no version reference. _version.py remains the single source at 0.3.0.dev20260808.
  • Tests-new / Tests-fix / Headless: N/A — no public method is added and no code behavior is changed, so there is nothing for a regression test to pin. The existing suite is retained as a guard that the branch does not disturb it.
  • Sibling structure / Sibling renames / camelCase: N/A — no file is created and no identifier is renamed.
  • Issue resolution: N/A — no Closes #N is claimed; the drift was found during the sweep rather than reported.

Summary: one finding, fixed in-branch; one acknowledged gap left tracked in #39 because the file it lives in is out of autonomous scope.

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit 97e577b into main Aug 11, 2026
5 checks passed
@dmccoystephenson
dmccoystephenson deleted the feature/readme-ci-trigger-accuracy branch August 11, 2026 07:07
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.

1 participant