diff --git a/develop-docs/sdk/getting-started/standards/repository-docs.mdx b/develop-docs/sdk/getting-started/standards/repository-docs.mdx new file mode 100644 index 00000000000000..83f0924b587681 --- /dev/null +++ b/develop-docs/sdk/getting-started/standards/repository-docs.mdx @@ -0,0 +1,116 @@ +--- +title: Repository and Documentation +sidebar_order: 5 +--- + +## AGENTS.md + +#### Rule + +Every SDK repo must have `AGENTS.md` covering: +* Architecture overview +* Testing conventions +* Build instructions +* Contribution expectations +* Commit attribution convention ([AI attribution](/sdk/getting-started/standards//code-submission#ai-attribution)) +* SDK-specific standard overrides - updated in same PR as architectural changes + +#### Enforcement + +* CI file existence check +* Human review for staleness + +#### Suggested Skill(s) + +* [`sentry-skills:agents-md`](https://github.com/getsentry/skills#available-skills) + +#### Per-SDK Override + + Content is SDK-specific. Requirement is universal. + +--- + +## CONTRIBUTING.md + +#### Rule + +Every SDK repo must have `CONTRIBUTING.md` covering: +* Setup instructions +* Development workflow +* Explicit quality bar +* Discussion-first policy +* AI tools section + +#### Enforcement + +* CI file existence check +* AGENT.md for update checking +* Content quality is human-reviewed. + +#### Per-SDK Override + + Setup/workflow are SDK-specific. Quality bar and AI sections use shared template. + +--- + +## PR Template + +#### Rule + +Every SDK repo must have a GitHub PR template with description structure guidance and linked-issue reminder. Not rigid sections — guidance for good free-form descriptions. + +#### Enforcement + +* File existence. + +#### Suggested Skill(s) + +* [`sentry-skills:create-pr`](https://github.com/getsentry/skills#available-skills) + +#### Per-SDK Override + + Wording varies. Linked-issue prompt is universal. + +--- + +## Documentation-with-Code + +#### Rule + +User-facing changes require corresponding docs: +* **New feature**: Docs PR to [sentry-docs](https://github.com/getsentry/sentry-docs/) +* **Behavior change**: Docs update, +* **Deprecation** Migration guide ([Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#deprecation-lifecycle)) +* **New config option**: Docs entry + +SDK PR links to docs PR. Neither merges without the other being at least approved. + +#### Enforcement + +* AGENTS.md instruction +* Human review + +#### Per-SDK Override + + + +--- + +## AI Context File Maintenance + +#### Rule + +AI context files (AGENTS.md, `.cursorrules`, `.github/copilot-instructions.md`, CLAUDE.md) are living documentation: updated with architectural changes, reviewed quarterly, periodically tested by having an AI tool attempt a contribution. + +#### Enforcement + +* Human review +* Quarterly review reminder + +#### Suggested Skill(s) + +* [`sentry-skills:agents-md`](https://github.com/getsentry/skills#available-skills) + +#### Per-SDK Override + + Which files exist varies. AGENTS.md is required ([AGENTS.md required](#agentsmd)); others recommended. \ No newline at end of file