Skip to content

docs: Add AGENTS.md #5579

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sentrivana wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs: Add AGENTS.md #5579

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8f2ebfb
docs: Add AGENTS.md
sentrivana Mar 3, 2026
17da4de
Add tox envs for mypy, ruff; tweak
sentrivana Mar 3, 2026
c090c88
.
sentrivana Mar 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Agent Instructions

## Tox

- Always run tox from the main `tox.venv`
- If there is no `tox.venv`, create one with `python -m venv tox.venv`, active it and run `pip install tox`

## Package Manager

Use **tox** for testing (not pytest directly):
- Test matrix configuration is in `tox.ini`
- Integration tests: `tox -e py3.14-{integration}-v{version}`
- Common tests: `tox -e py3.14-common`

## Type Checking

Use **tox** for type checking (not mypy directly):
- Run `tox -e mypy` before committing (must pass with zero errors)
- Strict mode enabled (`check_untyped_defs`, `disallow_untyped_defs`)

## Linting & Formatting

Use **tox** for linting (not ruff directly):
- `tox -e ruff`
- Full lint suite: `tox -e linters`
- Full lint suite must pass before committing

## Commit Attribution

AI commits MUST include:
```
Co-Authored-By: <agent model name> <noreply@anthropic.com>
```
Example: `Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>`

## Auto-Generated Files

Do NOT edit these directly — modify source scripts instead:
- `tox.ini` — generated by `scripts/populate_tox/populate_tox.py` from `scripts/populate_tox/tox.jinja`
- `.github/workflows/test-integrations-*.yml` — generated by `scripts/split_tox_gh_actions/split_tox_gh_actions.py`
- Regenerate all: `scripts/generate-test-files.sh`

## Adding Integrations to Test Suite

1. Add minimum version to `_MIN_VERSIONS` in `sentry_sdk/integrations/__init__.py`
2. Add config to `TEST_SUITE_CONFIG` in `scripts/populate_tox/config.py`
3. Add to group in `scripts/split_tox_gh_actions/split_tox_gh_actions.py`
4. Run `scripts/generate-test-files.sh`

## Integration Contract

- Don't crash applications or swallow exceptions
- Don't mutate object references or alter function signatures
- Don't leak file descriptors or make unexpected DB requests
- Write defensive code
- Use end-to-end tests (not mocks)

## Key Paths

| Path | Description |
|------|-------------|
| `sentry_sdk/integrations/` | integration modules |
| `sentry_sdk/ai/` | AI monitoring |
| `sentry_sdk/crons/` | Cron monitoring |
| `sentry_sdk/profiler/` | Performance profiling |
| `tests/integrations/{name}/` | Integration test suites |
| `scripts/populate_tox/config.py` | Test suite configuration |
1 change: 1 addition & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
AGENTS.md
14 changes: 14 additions & 0 deletions tox.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -327,6 +327,9 @@ deps =
linters: -r requirements-linting.txt
linters: werkzeug<2.3.0

ruff: -r requirements-linting.txt
mypy: -r requirements-linting.txt

# === Common ===
py3.8-common: hypothesis
common: pytest-asyncio
Expand Down Expand Up @@ -915,6 +918,8 @@ basepython =
# Tools like ruff and mypy have options that pin the target Python
# version (configured in pyproject.toml), ensuring consistent behavior.
linters: python3.14
mypy: python3.14
ruff: python3.14

commands =
{py3.7,py3.8}-boto3: pip install urllib3<2.0.0
Expand All @@ -933,3 +938,12 @@ commands =
ruff format --check tests sentry_sdk
mypy sentry_sdk
python scripts/find_raise_from_none.py

[testenv:mypy]
commands =
mypy sentry_sdk
Copy link

@cursor cursor bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

New mypy env missing werkzeug dependency for type checking

Medium Severity

The new [testenv:mypy] environment only installs requirements-linting.txt but is missing werkzeug<2.3.0, which is explicitly included in [testenv:linters] via linters: werkzeug<2.3.0. Because sentry_sdk/integrations/flask.py imports from werkzeug.datastructures import FileStorage, ImmutableMultiDict under TYPE_CHECKING, mypy will attempt to resolve those types. Since werkzeug has no ignore_missing_imports override in pyproject.toml, running tox -e mypy (as instructed in AGENTS.md) will fail with a missing import error that the linters env never surfaces.

Fix in Cursor Fix in Web


[testenv:ruff]
commands =
ruff check tests sentry_sdk
ruff format --check tests sentry_sdk
Comment on lines +942 to +949
Copy link

@sentry sentry bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: Manual changes to tox.ini for mypy and ruff environments will be lost when the auto-generation script populate_tox.py is run, as it overwrites the file.
Severity: MEDIUM

Suggested Fix

Instead of editing tox.ini directly, add the [testenv:mypy] and [testenv:ruff] configurations to the source template file, scripts/populate_tox/tox.jinja. This will ensure the changes are preserved when the auto-generation script runs.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: tox.ini#L942-L949

Potential issue: The `tox.ini` file is being manually modified to add `[testenv:mypy]`
and `[testenv:ruff]` sections. However, a comment at the top of `tox.ini` warns that the
file is auto-generated by `scripts/populate_tox/populate_tox.py` from the `tox.jinja`
template. The generation script opens `tox.ini` in write mode (`"w"`), which overwrites
the entire file. Since the new `mypy` and `ruff` environments are not present in the
`tox.jinja` template, these manual changes will be lost the next time the generation
script is executed. This will break the `tox -e mypy` and `tox -e ruff` commands
documented in `AGENTS.md`.

Did we get this right? 👍 / 👎 to inform future reviews.

Copy link

@cursor cursor bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Direct edits to auto-generated file will be lost

Medium Severity

The new [testenv:mypy] and [testenv:ruff] environments, along with their mypy: and ruff: factor-conditional deps and basepython entries, were added directly to tox.ini. However, tox.ini is auto-generated from scripts/populate_tox/tox.jinja, and the file itself begins with # DON'T EDIT THIS FILE BY HAND. tox.jinja has no corresponding changes, so the next run of scripts/generate-test-files.sh will silently overwrite and delete these new environments, making the tox -e mypy and tox -e ruff commands described in AGENTS.md disappear.

Additional Locations (1)

Fix in Cursor Fix in Web

Loading