|
| 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` |
0 commit comments