Repository navigation
docs(contributing): add agent-facing playbooks and architecture overview - #2007
Open
bearomorphism wants to merge 8 commits into
Open
bearomorphism wants to merge 8 commits into
bearomorphism wants to merge 8 commits into
Conversation
A general-audience map of Commitizen's subsystems (cli, commands, config, providers, changelog_formats, version_schemes, plugins) and how they wire together. Pairs with the existing contributor guide and is also the anchor for the new agent-facing docs that follow. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds docs/contributing/agents/ with a router index, a validation guide (targeted-test map + CI failure recipes), and five task playbooks for recurring contributions: add a version provider, add a changelog format, add or modify a CLI flag, deprecate a public API, and update snapshots/screenshots. Aggressively deduplicates against existing human docs (contributing.md, contributing_tldr.md, pull_request.md, command pages) by linking rather than restating. Adds one-line `For AI agents'' callouts in contributing.md and pull_request.md so human contributors discover the parallel track. Hooks the new pages into mkdocs nav under a new `For AI Agents'' section and into the mkdocs-llmstxt plugin so they appear in llms-full.txt. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
AGENTS.md is auto-loaded into every agent session, so its budget is tight. Trim it to the cross-cutting rules that an agent needs every time and link out to the new docs/contributing/architecture.md, docs/contributing/agents/index.md, and the validation guide and playbooks for everything else. Drops content that now duplicates the human contributor docs (bootstrap commands, poe cheat sheet, thin coding-guidelines section, CI-failure patterns) and replaces it with a Do-Not-Touch list of generated/managed files and a short list of mandatory PR reminders (AI disclosure, `poe all` before push, Steps to Test, Conventional Commits). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
🔍 Commitizen bump previewNo commits in this PR are eligible for a version bump. |
The repository convention is unwrapped paragraphs (one line per logical paragraph) - see existing contributing.md and pull_request.md where lines run to ~150-250 chars. The newly added AGENTS.md, architecture.md, and docs/contributing/agents/ files were authored with a ~70-char hard wrap, breaking the convention. Unwrap them to match. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
🔍 Commitizen bump previewNo commits in this PR are eligible for a version bump. |
Description
Adds an agent-shaped contributor track that links back to the existing human docs instead of restating them, and slims
AGENTS.mdto a routing layer.Why.
AGENTS.mdcurrently mixes routing, bootstrap commands, CI failure patterns, and coding guidelines that duplicatecontributing.md/contributing_tldr.md/pull_request.mdand drift out of sync. Nothing in the repo is reusable for recurring agent task types (add a provider, deprecate an API, regenerate snapshots, ...), so every session re-derives the workflow.What.
docs/contributing/architecture.md— one-page subsystem map (cli, commands, config, providers, changelog_formats, version_schemes, plugins) with extension points and config layering. General-audience.docs/contributing/agents/— routerindex.mdwith a source-of-truth map,validation.md(targeted-test selectors +poe allvspoe ci+ CI failure recipes), and 5 playbooks: add a version provider, add a changelog format, add/modify a CLI flag, deprecate a public API, update snapshots/screenshots.AGENTS.mdslimmed: keeps project pitch, key entrypoints, the "Read before changing" table; adds a "Do not touch" list of auto-managed files and the mandatory PR reminders; drops everything that now duplicates a human doc.contributing.mdandpull_request.md.mkdocs-llmstxtso the pages appear inllms-full.txt.Dedup rule. Every fact lives in exactly one place. The source-of-truth map in
agents/index.mdenforces it — agent docs link to human docs, never restate them.Checklist
Was generative AI tooling used to co-author this PR?
Generated-by: GitHub Copilot CLI following the guidelines
Code Changes
Docs-only PR. No Python, dependencies, or CI workflows changed.
uv run poe alllocally to ensure this change passes linter check and testsDocumentation Changes
uv run poe doclocally to ensure the documentation pages renders correctly (usedpoe doc:buildfor finite output)Expected Behavior
A new "For AI Agents" section appears under Contributing in the rendered docs,
llms-full.txtincludes the new pages, andAGENTS.mdis shorter and routes to them.Steps to Test This Pull Request
git checkout docs/agent-playbooks && uv sync --frozen --all-groupsuv run poe doc:build— confirm no broken-link warnings.site/contributing/agents/index.htmland walk the cross-links.site/llms-full.txtand confirm the new entries appear under Contributing.Additional Context
Split into 3 commits (architecture, agent docs + nav + callouts, AGENTS.md slim) for review clarity; squash-merge friendly.