Skip to content

AGENTS.md

Latest commit

 

History

History
89 lines (77 loc) · 4.55 KB

AGENTS.md

File metadata and controls

89 lines (77 loc) · 4.55 KB
Raw

AGENTS.md

Overview

  • sentry/sentry-symfony is a Composer library and Symfony bundle, not an application.
  • Use this file for repo-specific constraints that are easy to miss, and explore the codebase for current implementation details.

Compatibility Rules

  • The minimum supported PHP version for shipped code is 7.2. composer.json requires ^7.2 || ^8.0, so code added to this package must remain valid on PHP 7.2 unless support policy is intentionally being changed.
  • CI exercises Symfony 4.4 through 8, so Symfony-facing changes must keep the existing cross-version behavior intact.
  • Do not assume optional packages are installed. Messenger, Doctrine, Twig, Cache, and HttpClient support are guarded throughout the codebase with class_exists(), interface_exists(), and method_exists().
  • Preserve the existing compatibility style. Prefer feature detection and version-specific implementation classes over hard version checks when extending support for Symfony or Doctrine.
  • If you change tracing wrappers or compatibility behavior, verify the matching aliases in src/aliases.php and the version-specific files under src/Tracing/.
  • Listener priorities are intentional and covered by tests. Changing listener order usually requires test updates and may require an upgrade note.

Editing Guidance

  • Keep declare(strict_types=1); in PHP files.
  • Do not introduce PHP syntax or runtime assumptions that require newer than PHP 7.2 in shipped code unless the package minimum is being raised.
  • Follow the existing formatting rules from .php-cs-fixer.dist.php.
  • Services are private by default. Prefer existing FQCN service IDs and aliases instead of introducing new public services.
  • If a service or class has no intended public API surface but is public only for tests, wiring, or framework integration reasons, mark it @internal so users do not rely on it as a stable extension point and future refactors do not become accidental BC breaks.
  • XML fixtures are still relevant for older Symfony versions even though XML config support is skipped on Symfony 8+ in tests.
  • End-to-end behavior lives in tests/End2End/App. Prefer end-to-end coverage for regressions involving listeners, request scope data, tracing, logging, metrics, or console behavior.
  • DBAL compatibility tests use helpers in tests/DoctrineTestCase.php. Keep skip conditions and version-specific expectations intact.
  • tests/bootstrap.php registers ClockMock for tracing timing behavior. Do not remove timing assumptions without updating the related tests.
  • src/EventListener/TracingRequestListener.php temporarily injects the active request into RequestFetcher and clears it on terminate. Keep that set/reset lifecycle balanced if you change request tracing.
  • SentryBundle::SDK_VERSION is updated by the release action. Do not modify it manually as part of normal development changes.
  • BufferFlushPass, logging, and metrics code are sensitive to terminate-time behavior. Add end-to-end coverage when changing those paths.

Test Expectations

  • Add tests with every behavior change. This is a library repo and the existing test suite is broad.
  • For config changes, update the YAML, PHP, and XML DI fixtures together.
  • For optional-package behavior, mirror the existing pattern of conditional skips instead of forcing packages to exist in every environment.
  • After editing files, run the relevant formatting, lint, and test commands for the code you changed.
  • Before committing, run composer check.

Docs And Release Notes

  • README.md and CHANGELOG.md are updated manually during releases, so do not modify them as part of normal development changes.
  • If a change may require updates in the separate documentation repo, ask the user whether to review ../sentry-docs if that sibling checkout exists. If it does not exist, ask the user for the local docs path first. If they opt in, update that repo's master branch when safe, use git worktrees to inspect the relevant docs, and suggest any needed changes to avoid stale documentation.
  • CONTRIBUTING.md states that new code should include tests and notes that style checkers require PHP 7.4+ locally, but shipped code still has to comply with the package's PHP 7.2 baseline.

CI Notes

  • .github/workflows/tests.yaml runs a PHP/Symfony matrix and also includes jobs that remove optional packages before running tests.
  • .github/workflows/static-analysis.yaml runs PHP-CS-Fixer, PHPStan, and Psalm on a single recent PHP version rather than across the full test matrix.