Skip to content

Commit 788e052

Browse files
poccpocc
committed
Add docs/README.md as documentation index and quick start guide
1 parent c118b10 commit 788e052

File tree

1 file changed

+157
-0
lines changed

1 file changed

+157
-0
lines changed

‎docs/README.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Pre-Commit Hooks Documentation
2+
3+
This directory contains comprehensive documentation for the pre-commit-hooks project, with a focus on cross-platform testing and CI/CD.
4+
5+
## Quick Start
6+
7+
If you're experiencing test failures or setting up CI, start here:
8+
9+
1. **[CROSS_PLATFORM_FIXES.md](CROSS_PLATFORM_FIXES.md)** - Overview of all cross-platform testing fixes
10+
- Read this first to understand the complete picture
11+
- Learn about the root cause and key fixes
12+
13+
2. **[TEST_NORMALIZATION.md](TEST_NORMALIZATION.md)** - Patterns for test output normalization
14+
- Read this when adding new tests or debugging test failures
15+
- Understand when and how to normalize test output
16+
17+
3. **[MACOS_SDK_SETUP.md](MACOS_SDK_SETUP.md)** - Guide for macOS SDK configuration
18+
- Read this if you're working with clang-tidy or iwyu on macOS
19+
- Essential for understanding system header resolution
20+
21+
## Documentation Index
22+
23+
### Cross-Platform Testing
24+
25+
- **[CROSS_PLATFORM_FIXES.md](CROSS_PLATFORM_FIXES.md)**
26+
- Complete overview of fixes that made all 199 tests pass on Ubuntu, Windows, and macOS
27+
- Root cause analysis: integration tests using remote v1.3.4 instead of local code
28+
- Summary of all platform-specific fixes
29+
- Final results and key learnings
30+
31+
- **[TEST_NORMALIZATION.md](TEST_NORMALIZATION.md)**
32+
- Detailed patterns for normalizing test output across platforms
33+
- When to normalize and when NOT to normalize
34+
- Path separators, line endings, diagnostic names, trailing newlines
35+
- Platform-specific filtering strategies
36+
- Return code normalization rules
37+
38+
- **[MACOS_SDK_SETUP.md](MACOS_SDK_SETUP.md)**
39+
- Step-by-step guide for configuring macOS SDK for clang-tidy and iwyu
40+
- Environment variables (SDKROOT)
41+
- Compilation database configuration (-isysroot)
42+
- Test output filtering for system header noise
43+
- Common pitfalls and best practices
44+
45+
### Issue-Specific Documentation
46+
47+
- **[ISSUE_36_RESOLUTION.md](ISSUE_36_RESOLUTION.md)**
48+
- Detailed explanation of issue #36 (CMake integration test)
49+
- Root cause: missing cmake_minimum_required directive
50+
- Solution and test structure
51+
- CMake best practices for compilation databases
52+
53+
### Context and Timeline
54+
55+
- **[CONVERSATION_CONTEXT.md](CONVERSATION_CONTEXT.md)**
56+
- Complete conversation timeline from 64 test failures to zero
57+
- Chronological phases of fixes
58+
- User interactions and questions
59+
- Files modified and lessons learned
60+
- Success metrics (135/199 → 199/199 tests passing)
61+
62+
## Common Scenarios
63+
64+
### Scenario: Adding a New Test
65+
66+
1. Read [TEST_NORMALIZATION.md](TEST_NORMALIZATION.md) to understand normalization patterns
67+
2. Use `assert_equal()` from `tests/test_utils.py` for automatic path/line ending normalization
68+
3. Consider platform-specific filtering if your test involves:
69+
- clang-tidy on macOS (system header filtering)
70+
- iwyu on macOS (implementation header filtering)
71+
- Windows-specific diagnostic names
72+
73+
### Scenario: Test Failing on macOS Only
74+
75+
1. Read [MACOS_SDK_SETUP.md](MACOS_SDK_SETUP.md) to understand SDK configuration
76+
2. Check if error involves system headers (paths containing `/MacOSX.sdk/`)
77+
3. Review filtering logic in `tests/test_hooks.py`
78+
4. Ensure SDKROOT is set and `-isysroot` is in compilation database
79+
80+
### Scenario: Test Failing on Windows Only
81+
82+
1. Read [TEST_NORMALIZATION.md](TEST_NORMALIZATION.md) → "Path Separators" section
83+
2. Check for path separator issues (`\` vs `/`)
84+
3. Check for line ending issues (`\r\n` vs `\n`)
85+
4. Check for diagnostic name differences (return-mismatch vs return-type)
86+
87+
### Scenario: Integration Test Not Working
88+
89+
1. Read [CROSS_PLATFORM_FIXES.md](CROSS_PLATFORM_FIXES.md) → "Root Cause Analysis" section
90+
2. Ensure `integration_test()` uses local repository (`repo_root`), not remote
91+
3. Verify `compile_commands.json` is created and staged
92+
4. Check that test expectations match current tool behavior
93+
94+
### Scenario: CMake Integration Issues
95+
96+
1. Read [ISSUE_36_RESOLUTION.md](ISSUE_36_RESOLUTION.md)
97+
2. Ensure `cmake_minimum_required()` is in your CMakeLists.txt
98+
3. Verify `CMAKE_EXPORT_COMPILE_COMMANDS=ON` is set
99+
4. Check that clang-tidy can find the compilation database with `-p=build`
100+
101+
## Testing Commands
102+
103+
```bash
104+
# Run all tests
105+
python3 -m pytest tests/ -vvv
106+
107+
# Run specific test
108+
pytest tests/test_hooks.py::TestHooks::test_run[clang-tidy] -vvv
109+
110+
# Run tests for a specific command
111+
pytest tests/ -k "clang-tidy" -vvv
112+
113+
# Run integration tests only
114+
pytest tests/test_hooks.py -vvv
115+
116+
# Run on all platforms
117+
# Ubuntu/macOS:
118+
python3 -m pytest tests/ -vvv
119+
120+
# Windows:
121+
python -m pytest tests/ -vvv
122+
```
123+
124+
## Contributing
125+
126+
When modifying tests or adding new ones:
127+
128+
1. ✅ Test on all platforms (Ubuntu, Windows, macOS)
129+
2. ✅ Use built-in normalization functions (`assert_equal()`)
130+
3. ✅ Document platform-specific behaviors
131+
4. ✅ Follow selective filtering principles (filter noise, preserve errors)
132+
5. ✅ Update documentation if adding new patterns
133+
134+
## Success Story
135+
136+
This documentation represents the journey from:
137+
- **Before**: 64 test failures on Ubuntu, multiple failures on Windows/macOS
138+
- **After**: ✅ 199/199 tests passing on all platforms
139+
140+
**Total commits**: 25 commits documenting the entire journey
141+
**Key fix**: Integration tests now test local code instead of remote v1.3.4
142+
**Result**: Robust cross-platform test suite with comprehensive documentation
143+
144+
## Questions?
145+
146+
If you have questions not covered by this documentation:
147+
1. Check the conversation context in [CONVERSATION_CONTEXT.md](CONVERSATION_CONTEXT.md)
148+
2. Review the specific documentation file for your scenario
149+
3. Look at the implementation in `tests/test_utils.py` and `tests/test_hooks.py`
150+
4. File an issue on GitHub with details about your specific scenario
151+
152+
## Links
153+
154+
- **Repository**: https://github.com/pocc/pre-commit-hooks
155+
- **GitHub Actions**: See `.github/workflows/` for CI configuration
156+
- **Test Framework**: See `tests/test_utils.py` for integration test infrastructure
157+
- **Main Test Suite**: See `tests/test_hooks.py` for test implementations

0 commit comments

Comments
 (0)