Merge branch 'main' into chore/wrapping-improve-coding

Author: emmettbutler

.claude/CLAUDE.md

@@ -1,44 +1,2 @@
-# dd-trace-py Project Guide
-
-## Skills
-
-This project has custom skills that provide specialized workflows. **Always check if a skill exists before using lower-level tools.**
-
-### run-tests
-
-**Use whenever:** Running any tests, validating code changes, or when "test" is mentioned.
-
-**Purpose:** Intelligently runs the test suite using `scripts/run-tests`:
-- Discovers affected test suites based on changed files
-- Selects minimal venv combinations (avoiding hours of unnecessary test runs)
-- Manages Docker services automatically
-- Handles riot/hatch environment setup
-
-**Never:** Run pytest directly or use `hatch run tests:test` - these bypass the project's test infrastructure.
-
-**Usage:** Use the Skill tool with command "run-tests"
-
-### lint
-
-**Use whenever:** Formatting code, validating style/types/security, or before committing changes.
-
-**Purpose:** Runs targeted linting and code quality checks using `hatch run lint:*`:
-- Formats code with Black and Ruff auto-fixes
-- Validates style, types, and security
-- Checks spelling and documentation
-- Validates test infrastructure (suitespec, riotfile, etc.)
-- Supports running all checks or targeting specific files
-
-**Common Commands:**
-- `hatch run lint:fmt -- <file>` - Format a specific file after editing (recommended after every edit)
-- `hatch run lint:typing -- <file>` - Type check specific files
-- `hatch run lint:checks` - Run all quality checks (use before committing)
-- `hatch run lint:security -- -r <dir>` - Security scan a directory
-
-**Never:** Skip linting before committing. Always run `hatch run lint:checks` before pushing.
-
-**Usage:** Use the Skill tool with command "lint"
-
----
-
-<!-- Add more skills below as they are created -->
+<!-- Do not edit. Canonical instructions live in ../AGENTS.md -->
+@../AGENTS.md

.claude/settings.local.json

@@ -5,28 +5,38 @@
       "Bash(grep:*)",
       "Bash(python:*)",
       "Bash(./scripts/events/generate_stub.py:*)",
-      "Bash(hatch run lint:typing:*)",
       "Bash(./scripts/ddtest:*)",
-      "mcp__github__search_pull_requests",
-      "mcp__github__get_pull_request",
-      "mcp__atlassian__getJiraIssue",
-      "mcp__github__get_pull_request_review_comments",
+      "Bash(scripts/ddtest:*)",
+      "Bash(scripts/run-tests:*)",
+      "Bash(gh pr list:*)",
+      "Bash(git remote:*)",
+      "Bash(pyenv versions:*)",
+      "Bash(pyenv virtualenv:*)",
+      "Bash(mkdir:*)",
+      "Bash(docker compose build:*)",
       "Bash(riot list:*)",
-      "Read(//Users/brett.langdon/datadog/riot/**)",
+      "Bash(riot -v run:*)",
       "Bash(hatch run docs:*)",
+      "Bash(hatch run lint:fmt:*)",
+      "Bash(hatch run lint:typing:*)",
+      "Bash(hatch run lint:sg:*)",
       "Bash(cargo:*)",
       "Bash(source:*)",
       "Bash(pip install:*)",
-      "WebFetch(domain:ast-grep.github.io)",
       "Bash(git grep:*)",
       "Bash(ast-grep scan:*)",
-      "Bash(hatch run lint:sg:*)",
       "Bash(awk:*)",
-      "mcp__github__pull_request_read",
+      "WebFetch(domain:ast-grep.github.io)",
       "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "mcp__atlassian__getJiraIssue",
+      "mcp__github__search_pull_requests",
+      "mcp__github__get_pull_request",
+      "mcp__github__get_pull_request_review_comments",
+      "mcp__github__pull_request_read",
       "Skill(run-tests)",
-      "Bash(scripts/run-tests:*)"
+      "Skill(lint)"
     ],
     "deny": []
   }
-}
+}

.claude/skills/lint/SKILL.md

@@ -26,6 +26,14 @@ Use this skill when you:
 - Need to validate test infrastructure (suitespec, log messages)
 - Want to run comprehensive quality checks before pushing
 
+## Key Principles
+
+1. **Always format after editing** - Use `hatch run lint:fmt -- <file>` immediately after code changes
+2. **Run comprehensive checks before committing** - Use `hatch run lint:checks` before pushing
+3. **Target specific files** - Use `-- <file>` syntax to validate only what you changed, not the entire codebase
+4. **Fix auto-fixable issues** - Use `fmt` instead of manually fixing style issues
+5. **Type check after adding types** - Use `hatch run lint:typing -- <file>` after adding type annotations
+
 ## Quick Start
 
 **Run all checks (broad validation):**
@@ -48,7 +56,7 @@ hatch run lint:typing -- path/to/file.py
 ### Code Formatting
 
 #### `fmt` - Format code (recommended for most edits)
-Formats and validates code style using Black and Ruff.
+Formats and validates code style using Ruff.
 
 **Usage:**
 ```bash
@@ -63,7 +71,7 @@ hatch run lint:fmt -- ddtrace/contrib/flask/
 ```
 
 **What it does:**
-1. Runs Black formatter
+1. Runs the Ruff formatter
 2. Runs Ruff with --fix to auto-fix issues
 3. Re-validates with style checks
 
@@ -94,20 +102,21 @@ hatch run lint:style -- ddtrace/
 ```
 
 **What it validates:**
-- Black formatting
+- Ruff formatting
 - Ruff linting rules
 - Cython linting
 - C code formatting
 - CMake formatting
 
 **When to use:** To verify style compliance before committing without auto-fixes.
 
-#### `black_check` - Check Black formatting
-Validates Python code formatting with Black (no auto-fix).
+#### `format_check` - Check formatting
+
+Validates Python code formatting with `ruff format` (no auto-fix).
 
 **Usage:**
 ```bash
-hatch run lint:black_check -- ddtrace/tracer.py
+hatch run lint:format_check -- ddtrace/tracer.py
 ```
 
 **When to use:** Quick check of Python formatting before committing.

.claude/skills/run-tests/SKILL.md

@@ -26,6 +26,14 @@ Use this skill when you have:
 - Modified test infrastructure or configuration
 - Want to verify changes don't break existing functionality
 
+## Key Principles
+
+1. **Always use the run-tests skill** when testing code changes - it's optimized for intelligent suite discovery
+2. **Never run pytest directly** - bypasses the project's test infrastructure (use `scripts/run-tests` or `riot` via `scripts/ddtest`)
+3. **Minimal venvs for iteration** - run 1-2 venvs initially, expand only if needed
+4. **Use `--dry-run` first** - see what would run before executing
+5. **Follow official docs** - `docs/contributing-testing.rst` is the source of truth for testing procedures
+
 ## How This Skill Works
 
 ### Step 1: Identify Changed Files
@@ -116,6 +124,16 @@ For re-running specific tests:
 scripts/run-tests --venv <hash> -- -vv -k test_name
 ```
 
+## When Tests Fail
+
+When you encounter test failures, follow this systematic approach:
+
+1. **Review the failure details carefully** - Don't just skim the error, understand what's actually failing
+2. **Understand what's failing** - Don't blindly re-run; analyze the root cause
+3. **Make code changes** - Fix the underlying issue
+4. **Re-run with more verbosity if needed** - Use `-vv` or `-vvv` for detailed output
+5. **Iterate until tests pass** - Repeat the process with each fix
+
 ## Venv Selection Strategy in Detail
 
 ### Understanding Venv Hashes
@@ -255,13 +273,42 @@ scripts/run-tests --venv flask_py311 -- -vv -k test_view_called_twice
 - **Run tests without changes saved**: Make sure edits are saved first
 - **Iterate blindly**: Understand what's failing before re-running
 
+## Additional Testing Resources
+
+**For comprehensive testing guidance, refer to the contributing documentation:**
+
+- **[docs/contributing-testing.rst](../../docs/contributing-testing.rst)** - Detailed testing guidelines
+  - What kind of tests to write (unit tests, integration tests, e2e tests)
+  - When to write tests (feature development, bug fixes)
+  - Where to put tests in the repository
+  - Prerequisites (Docker, uv)
+  - Complete `scripts/run-tests` usage examples
+  - Riot environment management details
+  - Running specific test files and functions
+  - Test debugging strategies
+
+- **[docs/contributing.rst](../../docs/contributing.rst)** - PR and testing requirements
+  - All changes need tests or documented testing strategy
+  - How tests fit into the PR review process
+  - Testing expectations for different types of changes
+
+- **[docs/contributing-design.rst](../../docs/contributing-design.rst)** - Test architecture context
+  - How products, integrations, and core interact
+  - Where different types of tests should live
+  - Testing patterns for each library component
+
+**When to reference these docs:**
+- First time writing tests for this project → Read `contributing-testing.rst`
+- Understanding test requirements for PRs → Read `contributing.rst`
+- Need context on test architecture → Read `contributing-design.rst`
+
 ## Troubleshooting
 
 ### Docker services won't start
 ```bash
 # Manually check/stop services:
-docker-compose ps
-docker-compose down
+docker compose ps
+docker compose down
 ```
 
 ### Can't find matching suites