Unify contributor and agent guidance#947
Conversation
Consolidate human and coding-agent instructions in CONTRIBUTING.md, with AGENTS.md and CLAUDE.md linking to the shared guide. Remove volatile package inventories, align the Markdown and issue-writing rules, and document multi-runtime vocabulary snapshot updates in the guide, the vocab-tools README, and the add-vocab skill. Assisted-by: Codex:gpt-5.6-sol
✅ Deploy Preview for fedify-json-schema canceled.
|
📝 WalkthroughWalkthroughContribution documentation was rewritten with updated development, testing, AI usage, repository maintenance, documentation, pull request, and release guidance. Snapshot instructions were added for all supported runtimes, and related tooling metadata and links were updated. ChangesContribution Guidance
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request consolidates and updates the project's contribution guidelines and documentation. Key changes include a major rewrite of CONTRIBUTING.md to align rules for both human contributors and AI coding agents, updating references in CLAUDE.md and AGENTS.md, and adding instructions for updating multi-runtime snapshots in .agents/skills/add-vocab/SKILL.md and packages/vocab-tools/README.md. The review feedback suggests minor Markdown formatting improvements by removing unnecessary backslash escapes in references to AI_POLICY.md.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CONTRIBUTING.md`:
- Around line 592-604: Update the two quadruple-tilde fenced code blocks in the
commit-message example to include the text language identifier after the opening
fence, preserving their contents and closing fences.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: b0969292-19b8-4a84-9492-069e8fb99d07
📒 Files selected for processing (7)
.agents/skills/add-vocab/SKILL.md.hongdown.tomlAGENTS.mdAGENTS.mdCLAUDE.mdCONTRIBUTING.mdpackages/vocab-tools/README.md
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
This might be going beyond the scope of this PR, but I think one of the reasons CONTRIBUTING.md is so bloated is that it's all integrated instead of being separated by context. I'm certain that if CONTRIBUTING.md were split up by package, both humans and AI would be able to focus on the specific information they need for each context.
3 participants
Fedify's contribution rules had grown across AGENTS.md and CONTRIBUTING.md. Much of the material overlapped, but each document also contained details that the other audience was expected to know. This made the applicable rules depend on which entry point a contributor or coding agent happened to read, and it gave duplicated guidance room to drift as the repository changed.
This change treats CONTRIBUTING.md as the shared guide for both people and coding agents. AGENTS.md and CLAUDE.md remain as conventional discovery points, but both are symbolic links to that guide. The repository therefore keeps the filenames expected by agent tooling without maintaining separate copies of the same policy.
The consolidated guide is organized around the contribution workflow rather than around a package inventory. Package lists change often and were already maintained in the “Packages” section of README.md, so repeating them in contributor documentation made stale information more likely without helping contributors make decisions. The guide now points readers to the existing inventory and keeps its own focus on policies, development tasks, testing boundaries, and review expectations that apply across packages.
The rewrite also makes the Markdown rules consistent with the rest of the repository. It avoids bold text as structural emphasis and tells issue and pull request authors to keep prose paragraphs on one source line, then pass the description through
hongdown --stdin --no-line-width. Describing the command directly avoids a numeric line-width rule that some language models interpreted as an instruction to insert line breaks.The vocabulary workflow had a failure mode that the general testing guidance did not cover: generated-output snapshots are stored separately for Deno, Node.js, and Bun. The aggregate update command is therefore documented in CONTRIBUTING.md, packages/vocab-tools/README.md, and .agents/skills/add-vocab/SKILL.md so that contributors encounter it whether they begin from the general workflow, the package, or the task-specific guide. The vocabulary section also states that generated types are exported automatically, which keeps contributors from editing generated code or adding redundant exports.