Repository navigation
chore: Update the coding-agent setup and contributor docs - #9287
Merged
Merged
Conversation
- Add docs/ for maintainers: build and packaging, config options and CLI flags, releasing, design principles, glossary, and the ADR process. - Rewrite CONTRIBUTING.md: PR titles and bodies for release note readers, comments, invisible characters, writing for users. - Shrink AGENTS.md to commands, the "Do not" rules, and one-line rules that link to the docs. - Rewrite the feature-adr skill to run docs/ADRs as an interview; add release-notes, config-option, and cli-option skills. - Replace no-break spaces in the GitHub Action example in website/docs/installation.md.
…ebsite prefixes - Fix the malformed code spans in docs/releasing.md "Prerelease mode". - skipLibCheck: prefer false; tsconfig.esm.json sets true because third-party types broke builds. - Describe the rules from #9288: `docs:` and `website:` are not published, labels come from the title only, and reverts are published only for `feat` and `fix`. - ADR design PRs are `docs:`. - cli-option and config-option: filter while iterating, then build everything and update all snapshots.
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
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.
Summary
Moves the knowledge contributors need out of
AGENTS.mdinto docs for people underdocs/, rewrites the out-of-dateCONTRIBUTING.md, and updates the Claude Code skills to follow those docs. Agent files shrink to commands, the "Do not" rules, and one-line rules that link to the docs.Docs for maintainers and contributors (
docs/)build-and-packaging.md: layout, tooling, commands, every generated file and what regenerates it, the "if you change X, also do Y" table, bundled dictionaries, adding a package, and CI.config-and-cli.md: how to add or change a config option or a CLI flag, traced from past PRs. It covers the three registries the build enforces, the_mergestep it doesn't, and the Build Docs workflow that doesn't run on its own for CLI changes.releasing.md: release-drafter, the title and label table from chore: Release notes: exclude internal refactors, publish all breaking changes, strip tool attribution #9280 and chore: Release notes: leave out docs and website changes #9288, the Prepare Release flow, prerelease mode, and how to fix an entry after merge.design-principles.mdandglossary.md.ADRs/: the ADR process and templates, and how ADRs relate torfc/. Features are finalized before merge and archived about three months after shipping.CONTRIBUTING.md
enginesrequires>=22.18.0).docs:is for README files and the repo's docs, andwebsite:for site content. Neither is published.Agent setup
AGENTS.mdstays the source, andCLAUDE.mdstill imports it. The six "Do not" rules stay in full. Where a rule depends on a list that changes, it links to the list indocs/.workflow_dispatchwhen possible. Addworkflow_callonly to a new workflow without aconcurrencysection.feature-adris rewritten to rundocs/ADRs/as an interview. The worktree path now matches.gitignore, and links go to a feature's README.release-notes(fix a merged PR's entry, or audit the Prepare Release PR),config-option, andcli-option.Website
website/docs/installation.md. A copied workflow file failed to parse.Describes the release rules from #9288, so merge it after #9288. Follow-ups are tracked in #9282.