Setting Up a New SDK Repository

Overview

This playbook guides SDK maintainers through setting up a new SDK repository from scratch. It covers repository scaffolding, required documentation files, CI pipeline configuration, and verification steps to ensure AI tools can effectively contribute. By following these steps, the repository will have proper branch protection, documentation, testing infrastructure, and release automation in place.

Related resources:

• Repository Documentation Standards — required files and AI context
• Review and CI Standards — CI checks and review requirements
• Sentry Skills — automation tools for commits, PRs, and AGENTS.md

Steps

1. Repository scaffolding

Create the repository in the getsentry organization. You MUST configure branch protection rules:

• Require CI checks to pass (Required CI checks baseline)
• Require at least one approving review (Required reviewers)

You MUST set up a CODEOWNERS file with team members to automatically request reviews.

2. Required files

You MUST create the following files:

• AGENTS.md (AGENTS.md) — Use the AGENTS.md template. You SHOULD use the sentry-skills:agents-md skill to generate initial content.
• CONTRIBUTING.md (CONTRIBUTING.md) — Use the CONTRIBUTING.md template, customized for this SDK.
• .github/PULL_REQUEST_TEMPLATE.md (PR template) — Use the PR template.
• CHANGELOG.md or equivalent
• LICENSE file

3. CI pipeline

Set up CI with at minimum:

You MUST configure:

• Build verification
• Linting (Linting and formatting in CI)
• Type checking, if applicable for the language (Type checking in CI)
• Test suite
• Commit message format check (Commit message format)
• Secret scanning (Security practices)

4. AI context files

You MUST create AI context files (AI context file maintenance):

• AGENTS.md — required

You SHOULD create:

• CLAUDE.md
• .cursorrules
• .github/copilot-instructions.md

5. Release setup

You MUST configure release automation:

• Craft configuration (.craft.yml)
• Version bump script (e.g., scripts/bump-version.sh)
• Release workflow (e.g., .github/workflows/release.yml)

6. Rollback documentation

You MUST document rollback procedures (Rollback procedures):

• Who can publish and yank releases (at least two people)
• How to yank a release from the package registry
• Backup contact if the primary publisher is unavailable

7. Verify with an AI tool

Clone the repository fresh. Point an AI coding tool at it with no additional context. Ask it to make a sample contribution.

You MUST verify that:

• AGENTS.md gives the tool enough context to understand the architecture
• The tool can figure out how to run tests
• The tool creates a properly formatted commit
• The tool opens a draft PR with a meaningful description

If the tool cannot do this, the documentation needs work.

Referenced Standards

• AGENTS.md — AI context file requirements
• CONTRIBUTING.md — contributor guidelines
• PR template — pull request template structure
• AI context file maintenance — maintaining AI-readable documentation
• Required reviewers — review approval requirements
• Required CI checks baseline — minimum CI pipeline requirements
• Commit message format — conventional commit format
• Linting and formatting in CI — automated code style checks
• Type checking in CI — static type verification
• Security practices — secret scanning and security checks
• Rollback procedures — release rollback documentation