Principles
These working principles govern how SDK teams collaborate, review, and ship. They build on the SDK philosophy, which governs what we build and how our SDKs should behave.
Whether code is written by a human, an AI tool, or a collaboration, a human is accountable for every line that merges. The author's name on the PR is the owner. "The AI suggested it" is never a justification in review.
Guidelines exist to make the minimum quality of all contributions higher - internal and external, human and AI-assisted. A rising floor is more valuable than a rising ceiling.
If a rule can be checked by a machine, it must be checked by a machine. Human review time is the scarcest resource on the team - reserve it for decisions that require judgment: architecture, API design, user impact.
For non-trivial changes, agree on the approach before writing code. This applies to internal engineers as much as external contributors. An issue before a PR, and in important cases a spec before a PR. This is more important in the AI era, not less - generating code is cheap, but generating the wrong code wastes reviewer time. PRs without prior alignment will be closed without review.
Tests exist to verify the SDK does what users expect. A test that asserts nothing meaningful is worse than no test - it creates false confidence. This matters doubly for AI-generated tests, which frequently look correct but verify nothing. In the end, coverage is a diagnostic tool, not a goal in itself.
Code shows what. Commit messages, PR descriptions, and design docs explain why. This context is essential for future humans and AI tools working in the codebase. A commit with no explanation is a debt on every future reader.
Users of multiple Sentry SDKs should recognize the same concepts, behaviors, and terminology. But each SDK should feel native to its language and ecosystem. Cross-SDK standards define the concept, while per-SDK standards define the expression. Deviations from cross-SDK standards require explicit justification.
Small changes are easier to review, easier to revert, and easier for AI tools to generate correctly. Prefer multiple small PRs over one large one. A PR that does one thing well is worth more than a PR that does three things adequately.
Changes must solve a real problem. No speculative refactors, no "improvements" without a linked issue or measurable benefit. This gives engineers standing to reject changes - from humans or AI tools - that lack clear motivation. See Customer Value Matters for more information.
SDKs must never capture Sentry events for exceptions happening within the SDK itself, including within user-defined callbacks and hooks such as before_send or traces_sampler. We are already in an event capturing flow where the scope has been applied - capturing another event at that point would lead to undefined behavior. In the worst case, it creates a busy loop of creating and sending events repeatedly until the system crashes. If the SDK throws, swallow gracefully and emit an error-level log. In mobile SDKs, unhandled crashes will still make it to Sentry via crash handlers. See SDK Crash Detection for more details.
SDKs should integrate on the lowest level possible to capture as much of the runtime as they can. Hooking the runtime or a framework directly is preferred over requiring users to subclass specific base classes or mix in helpers. For example, the Python SDK monkey-patches core functionality in frameworks to automatically pick up on errors and integrate scope handling.
Work must be understandable without attending a meeting. Decisions, context, and outcomes belong in issues, docs, and PRs — not in someone's memory or a Slack thread.
A meeting may clarify and unblock, but it is never the record of what was decided. Every meeting that produces a decision must produce a written summary. The conversation ends; the document persists.
If you expect engineers (or AI tools) to follow a practice, it must be in a document that's discoverable and machine-readable. Verbal norms and tribal knowledge don't scale, and AI tools can't read them at all. See Write Down the Rules for more information.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").