chore: CI audit, docs overhaul, and release infrastructure#8
Merged
Conversation
CI: separated lint job (ubuntu/3.11, blocks matrix) from test job; reduced test matrix from 12 to 7 runs by dropping Windows and limiting 3.10 to ubuntu only; removed validate-adrs job which was a no-op since docs/adr/ is gitignored. Community files: added CONTRIBUTING.md with setup, test, and quality check instructions; added SECURITY.md; removed CODE_OF_CONDUCT.md. README: moved contributor-only Development section to CONTRIBUTING.md, updated nav link accordingly, replaced internal .agent/ link with GitHub Issues link. pyproject.toml: fixed placeholder URLs (your-org → kschlt), added Python 3.13 to classifiers. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
README rewritten for target audience (devs using AI-driven development): cut "Concept of ADRs" and baked it into the problem statement, condensed three-layer pitch, moved quick start and AI agent setup to the front, cleaned up learn more to only real links. Extracted into dedicated files: - TECHNICAL.md: layer deep dives with examples, policy schema, approval pipeline, directory structure, CI/CD, health check, project status - ROADMAP.md: what's coming (staged enforcement, full enforcement loop, DX polish) and recent additions with context on why each was built Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Future releases should be automated and self-documenting rather than manual. Added CHANGELOG.md (Keep a Changelog format) with historical entries back to 0.1.0 and an Unreleased section for current branch work. Created .github/workflows/release.yml using PyPI Trusted Publishing via OIDC — no secrets or tokens needed, CI authenticates via GitHub Actions identity. Added a Releasing section to CLAUDE.md with the 5-step release process. Removed ROADMAP.md "Recent Additions" section now superseded by the changelog, and linked CHANGELOG from README. After configuring the Trusted Publisher on pypi.org (documented in CLAUDE.md), releasing is: bump version + update CHANGELOG + tag + push. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
kschlt
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The repository needed to be ready for public use and ongoing open-source maintenance. Three gaps had to be closed: the CI was misconfigured and wasteful, the README was written for contributors rather than the target audience of AI-assisted developers, and there was no documented process or automation for cutting releases.
Approach
CI audit (
4326d7f): Separated lint from the test matrix so a lint failure blocks early without burning parallel runners. Trimmed the matrix from 12 to 7 by dropping Windows (no user-facing behavior difference) and limiting the Python 3.10 run to Ubuntu only. Removed thevalidate-adrsjob, which was a no-op becausedocs/adr/is gitignored.Community files (
4326d7f): Added CONTRIBUTING.md (extracted developer setup/test/quality instructions from README) and SECURITY.md. Removed CODE_OF_CONDUCT.md (generic boilerplate that added no value). Fixed placeholder URLs inpyproject.toml(your-org→kschlt) and added Python 3.13 to classifiers.README overhaul (
cdea481): Rewrote for the actual target audience. Extracted deep technical content (layer architecture, policy schema, approval pipeline, CI/CD integration) into TECHNICAL.md and future/historical context into ROADMAP.md, so the README stays focused on getting started quickly.Release infrastructure (
f5c9105): Added CHANGELOG.md (Keep a Changelog format, with historical entries back to 0.1.0). Created.github/workflows/release.ymlusing PyPI Trusted Publishing via OIDC — no secrets or API tokens needed; GitHub Actions authenticates directly. Documented the 5-step release process in CLAUDE.md. After one-time Trusted Publisher config on pypi.org, releasing is: bump version + update CHANGELOG + tag + push.What Was Tested
make qualitypasses (187 tests, ruff + mypy clean) after all changesRisks
Additive changes only for CHANGELOG, release workflow, and new docs files. The CI matrix reduction is a deliberate trade-off: Windows coverage is dropped, which is acceptable given the library's primary deployment target is Linux/macOS CI environments. The release workflow requires one manual step (configure Trusted Publisher on pypi.org) before the first automated release can run — documented in CLAUDE.md.