Skip to content

Commit d3b0d62

Browse files
philprimephilprime
authored
chore(ci): Add consistent workflow job naming (#5810)
1 parent 15e1008 commit d3b0d62

21 files changed

+313
-88
lines changed

‎.cursor/rules/github-workflow.mdc‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
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

‎.github/workflows/api-stability.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ on:
1818

1919
jobs:
2020
api-stability:
21+
name: Check API Stability (${{ matrix.version }})
2122
runs-on: macos-15
2223
strategy:
2324
matrix:

‎.github/workflows/assemble-xcframework-variant.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: "Assemble Sentry Cocoa XCFramework variant"
1+
name: Assemble XCFramework Variant
22

33
on:
44
workflow_call:
@@ -53,7 +53,7 @@ on:
5353

5454
jobs:
5555
assemble-xcframework-variant:
56-
name: Assemble ${{inputs.name}}${{inputs.suffix}} XCFramework Variant
56+
name: ${{inputs.name}}${{inputs.suffix}}
5757

5858
runs-on: macos-14
5959
steps:

‎.github/workflows/benchmarking.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ concurrency:
3131

3232
jobs:
3333
build-benchmark-test-target:
34-
name: Build app and test runner
34+
name: Build App and Test Runner
3535
runs-on: macos-14
3636
steps:
3737
- uses: actions/checkout@v4
@@ -93,7 +93,7 @@ jobs:
9393
**/Debug-iphoneos/iOS-Benchmarking-Runner.app
9494
9595
run-ui-tests-with-sauce:
96-
name: Run benchmarks on Sauce Labs
96+
name: Run Benchmarks ${{matrix.suite}}
9797
runs-on: ubuntu-latest
9898
needs: build-benchmark-test-target
9999
strategy:

‎.github/workflows/build-xcframework-variant-slices.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: "Build Sentry Cocoa XCFramework variant slices"
1+
name: Build XCFramework Slice
22

33
on:
44
workflow_call:

‎.github/workflows/changes-in-high-risk-code.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ concurrency:
99

1010
jobs:
1111
files-changed:
12-
name: Detect changed files
12+
name: Detect File Changes
1313
runs-on: ubuntu-latest
1414
# Map a step output to a job output
1515
outputs:
@@ -29,6 +29,7 @@ jobs:
2929
list-files: csv
3030

3131
validate-high-risk-code:
32+
name: Validate High-Risk Code
3233
if: needs.files-changed.outputs.high_risk_code == 'true'
3334
needs: files-changed
3435
runs-on: ubuntu-latest

‎.github/workflows/codeql-analysis.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: "CodeQL"
1+
name: CodeQL
22

33
on:
44
push:
@@ -16,7 +16,7 @@ concurrency:
1616

1717
jobs:
1818
analyze:
19-
name: Analyze
19+
name: Analyze (${{ matrix.language }})
2020
runs-on: macos-14
2121

2222
strategy:

‎.github/workflows/danger.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,5 @@ on:
66

77
jobs:
88
danger:
9+
name: Danger
910
uses: getsentry/github-workflows/.github/workflows/danger.yml@v2

‎.github/workflows/integration-test.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: CocoaPods Integration Tests
1+
name: Test CocoaPods
22
on:
33
push:
44
branches:
@@ -22,8 +22,8 @@ concurrency:
2222
cancel-in-progress: true
2323

2424
jobs:
25-
cocoapods:
26-
name: Integration Test
25+
test:
26+
name: CocoaPods Integration
2727
runs-on: macos-15
2828
steps:
2929
- name: Checkout Repository

‎.github/workflows/lint-clang-formatting.yml‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
name: Check Code Formatting
1+
name: Lint Clang
2+
23
on:
34
push:
45
branches:
@@ -29,10 +30,10 @@ on:
2930
- "Brewfile*" # Tools installation affects formatting environment
3031

3132
jobs:
32-
format-code:
33+
lint:
3334
# While ubuntu runners have clang-format preinstalled, they use an older version. We want to use the most recent one,
3435
# that we can easily install locally via brew.
35-
name: Check Formatting of Clang Format
36+
name: Lint
3637
runs-on: macos-15
3738
steps:
3839
- uses: actions/checkout@v4

0 commit comments

Comments
 (0)