Skip to content

Commit 12b7c04

Browse files
philprimephilprime
authored
fix: Add SentryTestUtilsTests to file-filters and create rule to prevent future issues (#6652)
1 parent 9766cb1 commit 12b7c04

File tree

2 files changed

+215
-0
lines changed

2 files changed

+215
-0
lines changed

‎.cursor/rules/file-filters.mdc‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
---
2+
description: |
3+
Apply this rule when making changes to the project's file hierarchy or structure, including:
4+
- Creating new directories (e.g., new test directories, sample projects, utility folders)
5+
- Renaming or moving existing directories
6+
- Restructuring code organization (e.g., splitting modules, reorganizing tests)
7+
- Adding new top-level folders or reorganizing subdirectories
8+
- Reviewing PRs that involve file/folder creation, deletion, or reorganization
9+
10+
This rule ensures that .github/file-filters.yml stays synchronized with the project structure
11+
so that GitHub Actions workflows are properly triggered by relevant file changes. Missing
12+
patterns can cause CI workflows to not run when they should, leading to undetected issues.
13+
alwaysApply: false
14+
---
15+
16+
# File Filters Configuration Rules
17+
18+
## Core Principles
19+
20+
### 1. Complete Coverage
21+
Every directory that contains code, tests, or configuration affecting CI should be included in at least one filter pattern.
22+
23+
### 2. Logical Grouping
24+
Files should be grouped with workflows they logically affect:
25+
- **Source changes** → Build and test workflows
26+
- **Test changes** → Test workflows
27+
- **Configuration changes** → Relevant validation workflows
28+
- **Script changes** → Workflows using those scripts
29+
30+
### 3. Hierarchy Awareness
31+
Use glob patterns (`**`) to capture all subdirectories and their contents recursively.
32+
33+
## Verification Checklist
34+
35+
Before submitting a PR that affects project structure:
36+
37+
- [ ] List all new or renamed directories
38+
- [ ] Check if each directory appears in `.github/file-filters.yml`
39+
- [ ] Add missing patterns to appropriate filter groups
40+
- [ ] Verify glob patterns match intended files
41+
- [ ] Test locally using the `dorny/paths-filter` action logic
42+
43+
## Pattern Best Practices
44+
45+
### Use Glob Patterns for Depth
46+
✅ **Good:**
47+
```yaml
48+
- "Sources/**" # Matches all files under Sources/
49+
- "Tests/**" # Matches all files under Tests/
50+
- "SentryTestUtils/**" # Matches all files under SentryTestUtils/
51+
```
52+
53+
❌ **Bad:**
54+
```yaml
55+
- "Sources/*" # Only matches one level deep
56+
- "Tests/" # Doesn't match files, only directory
57+
```
58+
59+
### Be Specific When Needed
60+
✅ **Good:**
61+
```yaml
62+
- "Samples/iOS-Cocoapods-*/**" # Matches multiple specific samples
63+
- "**/*.xctestplan" # Matches test plans anywhere
64+
- "scripts/ci-*.sh" # Matches CI scripts specifically
65+
```
66+
67+
❌ **Bad:**
68+
```yaml
69+
- "Samples/**" # Too broad, includes unrelated samples
70+
- "**/*" # Matches everything (defeats the purpose)
71+
```
72+
73+
### Include Related Configuration
74+
Always include configuration files that affect the workflow:
75+
76+
```yaml
77+
run_unit_tests_for_prs: &run_unit_tests_for_prs
78+
- "Sources/**"
79+
- "Tests/**"
80+
81+
# GH Actions - Changes to these workflows should trigger tests
82+
- ".github/workflows/test.yml"
83+
- ".github/file-filters.yml"
84+
85+
# Project files - Changes to project structure should trigger tests
86+
- "Sentry.xcodeproj/**"
87+
- "Sentry.xcworkspace/**"
88+
```
89+
90+
## Common Patterns by Workflow Type
91+
92+
These are complete, production-ready filter patterns for common workflow types. Use these as templates when adding new workflows or ensuring proper coverage.
93+
94+
### Unit Test Workflows
95+
**Required coverage:** All test-related directories (Tests, SentryTestUtils, SentryTestUtilsDynamic, SentryTestUtilsTests) must be included to ensure changes to test infrastructure trigger test runs.
96+
```yaml
97+
run_unit_tests_for_prs: &run_unit_tests_for_prs
98+
- "Sources/**" # Source code changes
99+
- "Tests/**" # Test changes
100+
- "SentryTestUtils/**" # Test utility changes
101+
- "SentryTestUtilsDynamic/**" # Dynamic test utilities
102+
- "SentryTestUtilsTests/**" # Test utility tests
103+
- ".github/workflows/test.yml" # Workflow definition
104+
- ".github/file-filters.yml" # Filter changes
105+
- "scripts/ci-*.sh" # CI scripts
106+
- "test-server/**" # Test infrastructure
107+
- "**/*.xctestplan" # Test plans
108+
- "Plans/**" # Test plan directory
109+
- "Sentry.xcodeproj/**" # Project structure
110+
```
111+
112+
### Lint Workflows
113+
```yaml
114+
run_lint_swift_formatting_for_prs: &run_lint_swift_formatting_for_prs
115+
- "**/*.swift" # All Swift files
116+
- ".github/workflows/lint-swift-formatting.yml"
117+
- ".github/file-filters.yml"
118+
- ".swiftlint.yml" # Linter config
119+
- "scripts/.swiftlint-version" # Version config
120+
```
121+
122+
### Build Workflows
123+
```yaml
124+
run_build_for_prs: &run_build_for_prs
125+
- "Sources/**" # Source code
126+
- "Samples/**" # Sample projects
127+
- ".github/workflows/build.yml"
128+
- ".github/file-filters.yml"
129+
- "Sentry.xcodeproj/**" # Project files
130+
- "Package*.swift" # SPM config
131+
- "scripts/sentry-xcodebuild.sh" # Build script
132+
```
133+
134+
## Troubleshooting
135+
136+
### PR Not Triggering Expected Workflows
137+
138+
1. **Check the paths-filter configuration** in the workflow:
139+
```yaml
140+
- uses: dorny/paths-filter@v3
141+
id: changes
142+
with:
143+
filters: .github/file-filters.yml
144+
```
145+
146+
2. **Verify the filter name** matches between `file-filters.yml` and workflow:
147+
```yaml
148+
# In file-filters.yml
149+
run_unit_tests_for_prs: &run_unit_tests_for_prs
150+
151+
# In workflow
152+
if: steps.changes.outputs.run_unit_tests_for_prs == 'true'
153+
```
154+
155+
3. **Test the pattern locally** using glob matching tools
156+
157+
### Pattern Not Matching Expected Files
158+
159+
Common issues:
160+
- Missing `**` for recursive matching
161+
- Using `*` instead of `**` for deep directories
162+
- Forgetting to include file extensions
163+
- Pattern too broad or too narrow
164+
165+
## Maintenance Guidelines
166+
167+
### Regular Audits
168+
Periodically review file-filters.yml to:
169+
- Remove patterns for deleted directories
170+
- Update patterns for renamed directories
171+
- Ensure new directories are covered
172+
- Verify patterns match current structure
173+
174+
### Documentation
175+
Each filter group should have comments explaining:
176+
- What the filter is for
177+
- Which workflow uses it
178+
- Special considerations
179+
180+
### Testing Changes
181+
When updating file-filters.yml:
182+
1. Create a test PR with changes in the new pattern
183+
2. Verify the expected workflow triggers
184+
3. Check that unrelated workflows don't trigger
185+
4. Review the GitHub Actions logs for filter results
186+
187+
## Error Prevention
188+
189+
### Pre-Merge Checklist for Structural Changes
190+
191+
When reviewing PRs that add/move/rename directories:
192+
193+
1. **Identify all affected directories**
194+
```bash
195+
gh pr view --json files --jq '.files[].path' | cut -d'/' -f1-2 | sort | uniq
196+
```
197+
198+
2. **Check each directory against file-filters.yml**
199+
```bash
200+
grep -r "DirectoryName" .github/file-filters.yml
201+
```
202+
203+
3. **Add missing patterns** to appropriate filter groups
204+
205+
4. **Verify the changes** trigger correct workflows
206+
207+
### Automated Detection (Future Enhancement)
208+
209+
Consider adding a script that:
210+
- Detects new top-level directories
211+
- Checks if they appear in file-filters.yml
212+
- Warns in PR if missing coverage
213+
214+
Example location: `.github/workflows/check-file-filters.yml`

‎.github/file-filters.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ run_unit_tests_for_prs: &run_unit_tests_for_prs
2424
- "Tests/**"
2525
- "SentryTestUtils/**"
2626
- "SentryTestUtilsDynamic/**"
27+
- "SentryTestUtilsTests/**"
2728

2829
# GH Actions
2930
- ".github/workflows/test.yml"

0 commit comments

Comments
 (0)