Other fix doc and readme badge#22
Merged
peterlau123 merged 37 commits intodevelopfrom Nov 27, 2025
Merged
Conversation
Fix documentation workflow that was failing because:
1. Doxygen wasn't installed (assumed to be present)
2. Upload path was wrong (build/docs/html vs docs/html)
Root cause:
The CMakeLists.txt docs target runs Doxygen with:
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
The Doxyfile specifies:
OUTPUT_DIRECTORY = docs
HTML_OUTPUT = html
So documentation is generated at:
<repo_root>/docs/html (not build/docs/html)
Changes:
1. Add step to install doxygen and graphviz
2. Remove '|| true' from docs build (fail fast if docs fail)
3. Add verification step to check docs/html exists
4. Fix upload path from 'build/docs/html' to 'docs/html'
This ensures the workflow fails clearly if documentation generation
fails, rather than silently continuing and failing at tar with a
confusing error message.
Fixes: tar: build/docs/html: Cannot open: No such file or directory
Add proper code coverage tracking with Codecov. Changes to codecov.yaml: 1. Add coverage status configuration (project & patch targets) 2. Configure precision, range, and thresholds 3. Expand ignore patterns (test/*, standalone/*, build*/*, cmake/*) 4. Configure PR comment layout and behavior Changes to ubuntu.yml workflow: 1. Add new 'run_coverage' job that: - Installs lcov for coverage report generation - Builds tests with ENABLE_TEST_COVERAGE=ON - Runs tests with ctest - Generates coverage.info using lcov - Filters out system and test files - Uploads to Codecov using codecov-action@v4 Coverage workflow: 1. Build with -fprofile-arcs -ftest-coverage flags (CMake option) 2. Run tests to generate .gcda files 3. Use lcov to capture coverage data 4. Filter out unwanted paths (/usr/*, test/*, conan/*) 5. Upload to Codecov with CODECOV_TOKEN secret Requirements: - Add CODECOV_TOKEN to repository secrets - Badge will be available at: https://codecov.io/gh/<user>/<repo> This enables: - Coverage tracking on every PR - Coverage badges in README - Coverage trends over time - Line-by-line coverage visualization Fixes the issue where codecov.yaml existed but no coverage was generated.
Add pre-commit configuration to enforce code quality and commit message
standards.
Features:
1. Commit Message Validation (commit-msg hook):
- Enforces Conventional Commits format: type(scope): subject
- Allowed types: feat, fix, docs, style, refactor, perf, test, build,
ci, chore, revert
- Commits with invalid format will be rejected
2. Code Quality Checks (pre-commit hook):
- File checks: trailing whitespace, EOF newline, large files, merge
conflicts, YAML/JSON syntax, private key detection
- C++ formatting: clang-format (auto-format on commit)
- CMake formatting: cmake-format and cmake-lint
- YAML/JSON formatting: prettier
- Shell scripts: shellcheck validation
- Python scripts: black formatting
3. Documentation:
- Added .pre-commit-setup.md with:
- Installation instructions
- Commit message format guide with examples
- List of allowed types and recommended scopes
- Troubleshooting guide
- CI integration notes
Setup Instructions:
pip install pre-commit
pre-commit install --hook-type commit-msg --hook-type pre-commit
Example valid commits:
feat(memory): add buffer pooling for better performance
fix(build): correct Windows DLL export declarations
docs(readme): update build instructions
ci(workflows): add coverage reporting
Excluded directories: build*, install*, .git, .github/workflows, docs/
This ensures consistent code quality and commit history across all
contributors.
Refs: https://www.conventionalcommits.org/
Add automatic branch name validation to enforce naming conventions. New Features: 1. Branch Name Validation (post-checkout hook): - Enforces format: <type>-<description> or <type>/<description> - Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore - Examples: feat-buffer-pooling, fix-memory-leak - Validates on git checkout -b or git switch -c - Shows helpful error message with examples if invalid 2. Protected Branches (skip validation): - main, master, develop - release/* (e.g., release/v1.0.0) - hotfix/* (e.g., hotfix/critical-bug) 3. Install Script (.githooks/install.sh): - One-command setup for all hooks - Configures git to use custom hooks directory - Installs pre-commit hooks - Makes hook scripts executable - Shows helpful summary 4. Updated Documentation: - Added branch naming section to .pre-commit-setup.md - Examples of valid/invalid branch names - Installation instructions updated Setup: ./.githooks/install.sh Or manually: git config core.hooksPath .githooks chmod +x .githooks/* Branch Validation Examples: ✅ git checkout -b feat-add-buffer-pooling ✅ git checkout -b fix/memory-leak ❌ git checkout -b my-feature (rejected - no type prefix) ❌ git checkout -b Feature-test (rejected - capital letter) This ensures consistent branch naming across all contributors and makes it easier to understand what each branch is for. Related to commit message validation from previous commit.
Refactor git hooks to work out-of-the-box with minimal user intervention
across macOS, Linux, and Windows.
Key Improvements:
1. Single Command Setup:
- Before: Multiple manual steps + bash scripts
- After: ONE command works on all platforms:
pip install pre-commit && pre-commit install --hook-type commit-msg --hook-type pre-commit --hook-type post-checkout
2. Cross-Platform Branch Validation:
- Replaced bash-only post-checkout hook with Python script
- Works on Windows, macOS, Linux (any platform with Python 3)
- Uses subprocess to call git (works everywhere)
- No platform-specific shell syntax
3. Integrated with pre-commit:
- Branch validation added as local pre-commit hook
- Automatically installed with pre-commit install
- No need for manual git config or custom hooks path
4. Better Documentation:
- Added SETUP.md with simple quick-start guide
- One command setup for new contributors
- Clear cross-platform support matrix
- Troubleshooting section
Files Changed:
- .githooks/check_branch_name.py (NEW) - Cross-platform Python validator
- .pre-commit-config.yaml - Added local branch name check
- SETUP.md (NEW) - Simple setup guide for contributors
- .pre-commit-setup.md - Updated with simplified instructions
- .pre-commit-hooks.yaml (NEW) - Hook metadata
Benefits:
✅ Works on Windows (Git Bash, PowerShell, WSL)
✅ Works on macOS (zsh, bash)
✅ Works on Linux (bash, zsh, sh)
✅ Only requires Python 3 + pip (already needed for development)
✅ Single command setup after git clone
✅ No platform-specific scripts
✅ Automatic validation on commit and branch checkout
User Experience:
1. Clone repo
2. Run: pip install pre-commit && pre-commit install --hook-type commit-msg --hook-type pre-commit --hook-type post-checkout
3. Done! All validations work automatically
No need to:
- Run separate install scripts
- Configure git hooks path manually
- Install platform-specific tools
- Deal with Windows compatibility issues
This makes contributing easier and ensures consistent code quality
across all platforms.
Add 👨💻 emoji in front of Developer-friendly feature for visual consistency with other features.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.