|
| 1 | +--- |
| 2 | +globs: .github/workflows/* |
| 3 | +alwaysApply: false |
| 4 | +--- |
| 5 | + |
| 6 | +# Cursor Rules for Sentry Cocoa Repository |
| 7 | + |
| 8 | +## GitHub Workflow Naming Convention |
| 9 | + |
| 10 | +### Workflow Names (Top-level `name:` field) |
| 11 | + |
| 12 | +Use concise, action-oriented names that describe the workflow's primary purpose: |
| 13 | + |
| 14 | +**Format:** `[Action] [Subject]` |
| 15 | + |
| 16 | +**Examples:** |
| 17 | +- ✅ `Release` (not "Release a new version") |
| 18 | +- ✅ `UI Tests` (not "Sentry Cocoa UI Tests") |
| 19 | +- ✅ `Benchmarking` (not "Run benchmarking tests") |
| 20 | +- ✅ `Lint SwiftLint` (not "Lint Swiftlint Formatting") |
| 21 | +- ✅ `Test CocoaPods` (not "CocoaPods Integration Test") |
| 22 | + |
| 23 | +### Job Names (Job-level `name:` field) |
| 24 | + |
| 25 | +Use clear, concise descriptions that avoid redundancy with the workflow name: |
| 26 | + |
| 27 | +**Principles:** |
| 28 | +1. **Remove redundant prefixes** - Don't repeat the workflow name |
| 29 | +2. **Use action verbs** - Start with what the job does |
| 30 | +3. **Avoid version-specific naming** - Don't include Xcode versions, tool versions, etc. |
| 31 | +4. **Keep it concise** - Maximum 3-4 words when possible |
| 32 | + |
| 33 | +**Patterns:** |
| 34 | + |
| 35 | +#### Build Jobs |
| 36 | +- ✅ `Build XCFramework Slice` (not "Build XCFramework Variant Slice") |
| 37 | +- ✅ `Assemble XCFramework Variant` (not "Assemble XCFramework" - be specific about variants) |
| 38 | +- ✅ `Build App and Test Runner` |
| 39 | +- ✅ `${{matrix.sdk}}` for platform-specific builds (e.g., "iphoneos", "macosx") |
| 40 | +- ✅ `${{inputs.name}}${{inputs.suffix}}` for variant assembly (e.g., "Sentry-Dynamic") |
| 41 | + |
| 42 | +#### Test Jobs |
| 43 | +- ✅ `Test ${{matrix.name}} V3 # Up the version with every change to keep track of flaky tests` |
| 44 | +- ✅ `Unit ${{matrix.name}}` (for unit test matrices) |
| 45 | +- ✅ `Run Benchmarks ${{matrix.suite}}` (for benchmarking matrices) |
| 46 | +- ✅ `Test SwiftUI V4 # Up the version with every change to keep track of flaky tests` |
| 47 | +- ✅ `Test Sentry Duplication V4 # Up the version with every change to keep track of flaky tests` |
| 48 | + |
| 49 | +**Note:** |
| 50 | +- Version numbers (V1, V2, etc.) are included in test job names for flaky test tracking, with explanatory comments retained. |
| 51 | +- For matrix-based jobs, use clean variable names that produce readable job names (e.g., `${{matrix.sdk}}`, `${{matrix.name}}`, `${{inputs.name}}${{inputs.suffix}}`). |
| 52 | +- When matrix includes multiple iOS versions, add a descriptive `name` field to each matrix entry (e.g., "iOS 16 Swift", "iOS 17 Swift") for clear job identification. |
| 53 | + |
| 54 | +#### Validation Jobs |
| 55 | +- ✅ `Validate XCFramework` (not "Validate XCFramework - Static") |
| 56 | +- ✅ `Validate SPM Static` (not "Validate Swift Package Manager - Static") |
| 57 | +- ✅ `Check API Stability` (not "API Stability Check") |
| 58 | + |
| 59 | +#### Lint Jobs |
| 60 | +- ✅ `Lint` (job name when workflow already specifies the tool, e.g., "Lint SwiftLint") |
| 61 | +- ❌ `SwiftLint` (redundant with workflow name "Lint SwiftLint") |
| 62 | +- ❌ `Clang Format` (redundant with workflow name "Lint Clang") |
| 63 | + |
| 64 | +#### Utility Jobs |
| 65 | +- ✅ `Collect App Metrics` (not "Collect app metrics") |
| 66 | +- ✅ `Detect File Changes` (not "Detect Changed Files") |
| 67 | +- ✅ `Release New Version` (not "Release a new version") |
| 68 | + |
| 69 | +### Version Tracking for Flaky Test Management |
| 70 | + |
| 71 | +For UI test jobs that need version tracking for flaky test management, include the version number in BOTH the job name AND a comment: |
| 72 | + |
| 73 | +**Format:** `[Job Name] V{number} # Up the version with every change to keep track of flaky tests` |
| 74 | + |
| 75 | +**Example:** |
| 76 | +```yaml |
| 77 | +name: Test iOS Swift V5 # Up the version with every change to keep track of flaky tests |
| 78 | +``` |
| 79 | + |
| 80 | +**Rationale:** |
| 81 | +- Version numbers must be in the job name because failure rate monitoring captures job names and ignores comments |
| 82 | +- Comments are kept to provide context and instructions for developers |
| 83 | + |
| 84 | +### Matrix Variables in Names |
| 85 | + |
| 86 | +When using matrix variables, prefer descriptive names over technical details: |
| 87 | + |
| 88 | +**Examples:** |
| 89 | +- ✅ `Test ${{matrix.name}}` where name = "iOS Objective-C", "tvOS Swift" |
| 90 | +- ✅ `Test ${{matrix.name}}` where name = "iOS 16 Swift", "iOS 17 Swift", "iOS 18 Swift" |
| 91 | +- ✅ `Unit ${{matrix.name}}` where name = "iOS 16 Sentry", "macOS 15 Sentry", "tvOS 18 Sentry" |
| 92 | +- ✅ `Run Benchmarks ${{matrix.suite}}` where suite = "High-end device", "Low-end device" |
| 93 | +- ✅ `Check API Stability (${{ matrix.version }})` where version = "default", "v9" |
| 94 | +- ❌ `Test iOS Swift Xcode ${{matrix.xcode}}` (version-specific) |
| 95 | + |
| 96 | +### Reusable Workflow Names |
| 97 | + |
| 98 | +For reusable workflows (workflow_call), use descriptive names that indicate their purpose: |
| 99 | + |
| 100 | +**Examples:** |
| 101 | +- ✅ `Build XCFramework Slice` |
| 102 | +- ✅ `Assemble XCFramework Variant` |
| 103 | +- ✅ `UI Tests Common` |
| 104 | + |
| 105 | +### Benefits of This Convention |
| 106 | + |
| 107 | +1. **Status Check Stability** - Names won't break when tool versions change |
| 108 | +2. **Cleaner GitHub UI** - Shorter, more readable names in PR checks |
| 109 | +3. **Better Organization** - Consistent patterns make workflows easier to understand |
| 110 | +4. **Future-Proof** - Version-agnostic naming reduces maintenance overhead |
| 111 | +5. **Branch Protection Compatibility** - Stable names work well with GitHub's branch protection rules |
| 112 | + |
| 113 | +### Anti-Patterns to Avoid |
| 114 | + |
| 115 | +❌ **Don't include:** |
| 116 | +- Tool versions (Xcode 15.4, Swift 5.9, etc.) unless they are relevant to the job |
| 117 | +- Redundant workflow prefixes ("Release /", "UI Tests /") |
| 118 | +- Overly verbose descriptions |
| 119 | +- Technical implementation details in user-facing names |
| 120 | +- Lowercase inconsistency |
| 121 | + |
| 122 | +❌ **Examples of what NOT to do:** |
| 123 | +- "Release / Build XCFramework Variant Slice (Sentry, mh_dylib, -Dynamic, sentry-dynamic) / Build XCFramework Slice" |
| 124 | +- "UI Tests / UI Tests for iOS-Swift Xcode 15.4 - V5" |
| 125 | +- "Lint Swiftlint Formatting / SwiftLint" (redundant job name) |
| 126 | +- "Build Sentry Cocoa XCFramework Variant Slice" |
| 127 | + |
| 128 | +### Implementation Notes |
| 129 | + |
| 130 | +- Always include version numbers in test job names AND keep explanatory comments for flaky test management |
| 131 | +- Keep matrix variable usage minimal and descriptive |
| 132 | +- Ensure names remain meaningful when viewed in GitHub's status check UI |
| 133 | +- Test names in the GitHub PR interface before committing changes |
| 134 | +- For lint workflows, use simple "Lint" job name since the tool is already specified in the workflow name |
0 commit comments