|
| 1 | +# .github |
| 2 | + |
| 3 | +> Instructions for LLM agents. Keep edits minimal (headers + bullets). Use `/agents-md` skill when editing. |
| 4 | +
|
| 5 | +## Workflow Naming |
| 6 | + |
| 7 | +**Workflow names** — concise, action-oriented: `[Action] [Subject]` |
| 8 | + |
| 9 | +- `Release`, `UI Tests`, `Benchmarking`, `Lint SwiftLint`, `Test CocoaPods` |
| 10 | + |
| 11 | +**Job names** — no redundant prefixes, use action verbs, max 3-4 words, no tool versions: |
| 12 | + |
| 13 | +| Category | Examples | |
| 14 | +| -------- | ----------------------------------------------------------------------- | |
| 15 | +| Build | `Build XCFramework Slice`, `${{matrix.sdk}}` | |
| 16 | +| Test | `Test ${{matrix.name}} V3 # Up the version...`, `Unit ${{matrix.name}}` | |
| 17 | +| Validate | `Validate XCFramework`, `Check API Stability` | |
| 18 | +| Lint | `Lint` (when workflow name already specifies tool) | |
| 19 | +| Utility | `Collect App Metrics`, `Detect File Changes` | |
| 20 | + |
| 21 | +### Flaky Test Tracking |
| 22 | + |
| 23 | +Version number in BOTH job name AND comment (monitoring captures names, ignores comments): |
| 24 | + |
| 25 | +```yaml |
| 26 | +name: Test iOS Swift V5 # Up the version with every change to keep track of flaky tests |
| 27 | +``` |
| 28 | +
|
| 29 | +## Concurrency |
| 30 | +
|
| 31 | +### Pattern 1: Conditional (most common) |
| 32 | +
|
| 33 | +```yaml |
| 34 | +concurrency: |
| 35 | + group: ${{ github.workflow }}-${{ github.ref }} |
| 36 | + cancel-in-progress: ${{ github.event_name == 'pull_request' }} |
| 37 | +``` |
| 38 | +
|
| 39 | +Cancels PR runs on new push. Never cancels main/release/schedule. |
| 40 | +
|
| 41 | +### Pattern 2: Always Cancel (PR-only workflows) |
| 42 | +
|
| 43 | +```yaml |
| 44 | +concurrency: |
| 45 | + group: ${{ github.workflow }}-${{ github.ref }} |
| 46 | + cancel-in-progress: true |
| 47 | +``` |
| 48 | +
|
| 49 | +### Pattern 3: Fixed Group (special cases) |
| 50 | +
|
| 51 | +```yaml |
| 52 | +concurrency: |
| 53 | + group: "auto-update-tools" |
| 54 | + cancel-in-progress: true |
| 55 | +``` |
| 56 | +
|
| 57 | +Each concurrency block must include comments explaining purpose, resource considerations, and branch protection logic. |
| 58 | +
|
| 59 | +## File Filters (`file-filters.yml`) |
| 60 | + |
| 61 | +- Every directory with code/tests/config must appear in at least one filter |
| 62 | +- Use `**` for recursive matching (`Sources/**`, not `Sources/*`) |
| 63 | +- Include related workflow and config files in each filter group |
| 64 | + |
| 65 | +### Templates |
| 66 | + |
| 67 | +```yaml |
| 68 | +# Unit tests |
| 69 | +run_unit_tests_for_prs: |
| 70 | + - "Sources/**" |
| 71 | + - "Tests/**" |
| 72 | + - "SentryTestUtils/**" |
| 73 | + - "SentryTestUtilsDynamic/**" |
| 74 | + - "SentryTestUtilsTests/**" |
| 75 | + - ".github/workflows/test.yml" |
| 76 | + - ".github/file-filters.yml" |
| 77 | + - "scripts/ci-*.sh" |
| 78 | + - "test-server/**" |
| 79 | + - "**/*.xctestplan" |
| 80 | + - "Plans/**" |
| 81 | + - "Sentry.xcodeproj/**" |
| 82 | +``` |
| 83 | + |
| 84 | +```yaml |
| 85 | +# Lint |
| 86 | +run_lint_swift_formatting_for_prs: |
| 87 | + - "**/*.swift" |
| 88 | + - ".github/workflows/lint-swift-formatting.yml" |
| 89 | + - ".github/file-filters.yml" |
| 90 | + - ".swiftlint.yml" |
| 91 | +``` |
| 92 | + |
| 93 | +```yaml |
| 94 | +# Build |
| 95 | +run_build_for_prs: |
| 96 | + - "Sources/**" |
| 97 | + - "Samples/**" |
| 98 | + - ".github/workflows/build.yml" |
| 99 | + - ".github/file-filters.yml" |
| 100 | + - "Sentry.xcodeproj/**" |
| 101 | + - "Package*.swift" |
| 102 | +``` |
| 103 | + |
| 104 | +### When changing project structure |
| 105 | + |
| 106 | +1. List all new/renamed directories |
| 107 | +2. Check each against `file-filters.yml` |
| 108 | +3. Add missing patterns to appropriate filter groups |
0 commit comments