From 0d20bfe0d7bd895ea5dc6aee3a383dc66c64cd10 Mon Sep 17 00:00:00 2001 From: Michael Hoffmann Date: Mon, 23 Jun 2025 11:44:32 +0200 Subject: [PATCH] Add Claude & Cursor agent rules wip --- .cursor/rules/release-process.mdc | 68 ++++++++++++++++++ .cursor/rules/sentry-php.mdc | 116 ++++++++++++++++++++++++++++++ CLAUDE.md | 111 ++++++++++++++++++++++++++++ 3 files changed, 295 insertions(+) create mode 100644 .cursor/rules/release-process.mdc create mode 100644 .cursor/rules/sentry-php.mdc create mode 100644 CLAUDE.md diff --git a/.cursor/rules/release-process.mdc b/.cursor/rules/release-process.mdc new file mode 100644 index 000000000..ea4780ea6 --- /dev/null +++ b/.cursor/rules/release-process.mdc @@ -0,0 +1,68 @@ +--- +globs: CHANGELOG.md +alwaysApply: false +--- +# Sentry PHP SDK Release Process + +## Release Process + +To prepare a new release (e.g., version 4.14.0): + +1. **Update master branch**: Always ensure master is up-to-date first + ```bash + git checkout master + git pull origin master + ``` + +2. **Create release branch**: Create a branch named `prepare-X.Y.Z` + ```bash + git checkout -b prepare-4.14.0 + ``` + +3. **Find changes since last release**: Check commits since the last version tag + ```bash + git log --oneline --no-merges 4.13.0..HEAD + ``` + +4. **Update CHANGELOG.md**: Add new version section with: + - Version number and announcement text + - Features section for new features + - Bug Fixes section for bug fixes + - Misc section for documentation/readme updates + - Use format: `- Description [(#PR)](mdc:https:/github.com/getsentry/sentry-php/pull/PR)` + +## CHANGELOG.md Format + +```markdown +## X.Y.Z + +The Sentry SDK team is happy to announce the immediate availability of Sentry PHP SDK vX.Y.Z. + +### Features + +- New feature description [(#1234)](mdc:https:/github.com/getsentry/sentry-php/pull/1234) + +### Bug Fixes + +- Bug fix description [(#1235)](mdc:https:/github.com/getsentry/sentry-php/pull/1235) + +### Misc + +- Documentation/misc changes [(#1236)](mdc:https:/github.com/getsentry/sentry-php/pull/1236) +``` + +## Committing Changes + +After updating CHANGELOG.md: + +1. **Stage only the changelog**: `git add CHANGELOG.md` +2. **Create simple commit**: `git commit -m "Prepare X.Y.Z"` + - Use simple commit message format + - Don't include additional descriptions or generated tags + +## Common Commands + +- Check git status: `git status` +- View recent commits: `git log --oneline -10` +- Create branch: `git checkout -b branch-name` +- Update from remote: `git pull origin master` diff --git a/.cursor/rules/sentry-php.mdc b/.cursor/rules/sentry-php.mdc new file mode 100644 index 000000000..ec5ddba01 --- /dev/null +++ b/.cursor/rules/sentry-php.mdc @@ -0,0 +1,116 @@ +--- +description: +globs: +alwaysApply: true +--- +# Sentry PHP SDK Development Rules + +## Project Overview +The Sentry PHP SDK is an official error tracking and monitoring library for PHP applications. It provides error reporting, performance monitoring, and crash reporting capabilities. + +## Core Requirements + +### PHP Version Compatibility +- All code must support PHP 7.2 and up (including PHP 8.x) +- Use appropriate type hints and features compatible with the minimum PHP version +- Test against multiple PHP versions in CI + +### Breaking Changes Policy +- No breaking changes to any public methods are allowed in minor/patch releases +- Existing methods in interfaces cannot be altered without major version bump +- Follow semantic versioning strictly as defined in [CONTRIBUTING.md](mdc:CONTRIBUTING.md) + +## Code Quality Standards + +### Code Style and Linting +- All code must adhere to the project's code style +- Run `composer cs-check` to check for linting errors +- Use `composer cs-fix` to automatically fix linting issues +- Configuration is in [.php-cs-fixer.dist.php](mdc:.php-cs-fixer.dist.php) + +### Static Analysis +- Code must pass PHPStan analysis (`composer phpstan`) +- Code must pass Psalm analysis (`composer psalm`) +- Baseline files exist for legacy issues: [phpstan-baseline.neon](mdc:phpstan-baseline.neon) and [psalm-baseline.xml](mdc:psalm-baseline.xml) + +### Testing Requirements +- All new features require comprehensive tests +- Tests are located in the [tests/](mdc:tests) directory +- Run tests with `composer tests` or `vendor/bin/phpunit` +- Test structure mirrors the src/ directory structure +- Use PHPUnit for unit testing + +## Project Structure + +### Main Source Code +- Core SDK code is in [src/](mdc:src) directory +- Entry point functions are in [src/functions.php](mdc:src/functions.php) +- Main client class is [src/Client.php](mdc:src/Client.php) +- Configuration handled by [src/Options.php](mdc:src/Options.php) + +### Key Components +- **Events**: [src/Event.php](mdc:src/Event.php) - Core event structure +- **Error Handling**: [src/ErrorHandler.php](mdc:src/ErrorHandler.php) - Error capture +- **Integrations**: [src/Integration/](mdc:src/Integration) - Framework integrations +- **Transport**: [src/Transport/](mdc:src/Transport) - Data transmission +- **Serialization**: [src/Serializer/](mdc:src/Serializer) - Data serialization +- **Tracing**: [src/Tracing/](mdc:src/Tracing) - Performance monitoring +- **Profiling**: [src/Profiling/](mdc:src/Profiling) - Performance profiling + +### Dependencies +- Core dependencies defined in [composer.json](mdc:composer.json) +- PSR-7 HTTP messages via guzzlehttp/psr7 +- Symfony OptionsResolver for configuration +- PSR-3 logging interface support + +## Development Workflow + +### Code Formatting +- Always add import statements for all classes and functions used +- Use proper PHP namespacing (`Sentry\` namespace) +- Follow PSR-4 autoloading standards + +### Commit Messages +- Follow the commit message format: https://develop.sentry.dev/commit-messages/#commit-message-format +- Use conventional commits for automatic changelog generation + +### Pull Request Guidelines +- Read [CONTRIBUTING.md](mdc:CONTRIBUTING.md) before submitting PRs +- PRs use LOGAF scale for feedback (Low, Medium, High priority comments) +- Ensure all CI checks pass (tests, linting, static analysis) +- Add appropriate tests for new functionality + +## Common Patterns + +### Error Handling +- Use proper exception handling and logging +- Capture exceptions with appropriate context +- Follow Sentry's error reporting best practices + +### Configuration +- Use [src/Options.php](mdc:src/Options.php) for configuration management +- Support environment-based configuration +- Provide sensible defaults + +### Integration Development +- New integrations go in [src/Integration/](mdc:src/Integration) +- Follow existing integration patterns +- Provide proper setup and teardown methods +- Document integration usage + +### Testing Patterns +- Test files mirror source structure in [tests/](mdc:tests) +- Use descriptive test method names +- Include both positive and negative test cases +- Mock external dependencies appropriately + +## Documentation +- Update [CHANGELOG.md](mdc:CHANGELOG.md) for user-facing changes +- Follow upgrade guides pattern for breaking changes +- Maintain compatibility with official Sentry documentation + +## Release Process +- Releases are managed through GitHub Actions and Craft +- Follow the release process outlined in [CONTRIBUTING.md](mdc:CONTRIBUTING.md) +- Two-person approval process for releases +- Automatic changelog generation from conventional commits diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..a4b9f9974 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,111 @@ +# Sentry PHP SDK Development Rules + +## Project Overview +The Sentry PHP SDK is an official error tracking and monitoring library for PHP applications. It provides error reporting, performance monitoring, and crash reporting capabilities. + +## Core Requirements + +### PHP Version Compatibility +- All code must support PHP 7.2 and up (including PHP 8.x) +- Use appropriate type hints and features compatible with the minimum PHP version +- Test against multiple PHP versions in CI + +### Breaking Changes Policy +- No breaking changes to any public methods are allowed in minor/patch releases +- Existing methods in interfaces cannot be altered without major version bump +- Follow semantic versioning strictly as defined in [CONTRIBUTING.md](mdc:CONTRIBUTING.md) + +## Code Quality Standards + +### Code Style and Linting +- All code must adhere to the project's code style +- Run `composer cs-check` to check for linting errors +- Use `composer cs-fix` to automatically fix linting issues +- Configuration is in [.php-cs-fixer.dist.php](mdc:.php-cs-fixer.dist.php) + +### Static Analysis +- Code must pass PHPStan analysis (`composer phpstan`) +- Code must pass Psalm analysis (`composer psalm`) +- Baseline files exist for legacy issues: [phpstan-baseline.neon](mdc:phpstan-baseline.neon) and [psalm-baseline.xml](mdc:psalm-baseline.xml) + +### Testing Requirements +- All new features require comprehensive tests +- Tests are located in the [tests/](mdc:tests) directory +- Run tests with `composer tests` or `vendor/bin/phpunit` +- Test structure mirrors the src/ directory structure +- Use PHPUnit for unit testing + +## Project Structure + +### Main Source Code +- Core SDK code is in [src/](mdc:src) directory +- Entry point functions are in [src/functions.php](mdc:src/functions.php) +- Main client class is [src/Client.php](mdc:src/Client.php) +- Configuration handled by [src/Options.php](mdc:src/Options.php) + +### Key Components +- **Events**: [src/Event.php](mdc:src/Event.php) - Core event structure +- **Error Handling**: [src/ErrorHandler.php](mdc:src/ErrorHandler.php) - Error capture +- **Integrations**: [src/Integration/](mdc:src/Integration) - Framework integrations +- **Transport**: [src/Transport/](mdc:src/Transport) - Data transmission +- **Serialization**: [src/Serializer/](mdc:src/Serializer) - Data serialization +- **Tracing**: [src/Tracing/](mdc:src/Tracing) - Performance monitoring +- **Profiling**: [src/Profiling/](mdc:src/Profiling) - Performance profiling + +### Dependencies +- Core dependencies defined in [composer.json](mdc:composer.json) +- PSR-7 HTTP messages via guzzlehttp/psr7 +- Symfony OptionsResolver for configuration +- PSR-3 logging interface support + +## Development Workflow + +### Code Formatting +- Always add import statements for all classes and functions used +- Use proper PHP namespacing (`Sentry\` namespace) +- Follow PSR-4 autoloading standards + +### Commit Messages +- Follow the commit message format: https://develop.sentry.dev/commit-messages/#commit-message-format +- Use conventional commits for automatic changelog generation + +### Pull Request Guidelines +- Read [CONTRIBUTING.md](mdc:CONTRIBUTING.md) before submitting PRs +- PRs use LOGAF scale for feedback (Low, Medium, High priority comments) +- Ensure all CI checks pass (tests, linting, static analysis) +- Add appropriate tests for new functionality + +## Common Patterns + +### Error Handling +- Use proper exception handling and logging +- Capture exceptions with appropriate context +- Follow Sentry's error reporting best practices + +### Configuration +- Use [src/Options.php](mdc:src/Options.php) for configuration management +- Support environment-based configuration +- Provide sensible defaults + +### Integration Development +- New integrations go in [src/Integration/](mdc:src/Integration) +- Follow existing integration patterns +- Provide proper setup and teardown methods +- Document integration usage + +### Testing Patterns +- Test files mirror source structure in [tests/](mdc:tests) +- Use descriptive test method names +- Include both positive and negative test cases +- Mock external dependencies appropriately + +## Documentation +- Update [CHANGELOG.md](mdc:CHANGELOG.md) for user-facing changes +- Follow upgrade guides pattern for breaking changes +- Maintain compatibility with official Sentry documentation + +## Release Process +- Releases are managed through GitHub Actions and Craft +- Follow the release process outlined in [CONTRIBUTING.md](mdc:CONTRIBUTING.md) +- Two-person approval process for releases +- Automatic changelog generation from conventional commits