Skip to content

.pre-commit-setup.md

Latest commit

 

History

History
204 lines (152 loc) · 4.61 KB

.pre-commit-setup.md

File metadata and controls

204 lines (152 loc) · 4.61 KB

Pre-commit Setup Guide

This repository uses pre-commit to ensure code quality and enforce commit message conventions.

Quick Setup

After cloning the repository, run ONE command:

pip install pre-commit && pre-commit install --hook-type commit-msg --hook-type pre-commit --hook-type post-checkout

That's it! The hooks will now run automatically on every commit and branch checkout.

Optional: Test the setup

# Run all checks manually
pre-commit run --all-files

# Test branch name validation
python3 .githooks/check_branch_name.py

Branch Naming Convention

All branch names must follow this format:

<type>-<description>  or  <type>/<description>

Examples

✅ Valid branch names:

feat-buffer-pooling
fix-windows-dll-exports
docs-update-readme
refactor/simplify-tensor-allocation
ci-add-coverage-reporting
test-buffer-manager

❌ Invalid branch names:

buffer_pooling        (no type prefix)
Feat-something        (capital letter)
feature-test          (wrong type, use 'feat')
my-branch             (no type prefix)

Protected Branches (No Validation)

These branches don't require the naming convention:

  • main, master, develop
  • release/* (e.g., release/v1.0.0)
  • hotfix/* (e.g., hotfix/critical-bug)

Commit Message Format

All commit messages must follow the Conventional Commits format:

<type>(<scope>): <subject>

[optional body]

[optional footer]

Allowed Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only changes
  • style: Code style changes (formatting, no logic change)
  • refactor: Code refactoring (neither fixes a bug nor adds a feature)
  • perf: Performance improvements
  • test: Adding or updating tests
  • build: Build system or dependency changes
  • ci: CI/CD configuration changes
  • chore: Other changes (tooling, maintenance)
  • revert: Revert a previous commit

Examples

✅ Good commit messages:

feat(memory): add buffer pooling for better performance
fix(build): correct Windows DLL export declarations
docs(readme): update build instructions for macOS
refactor(tensor): simplify memory allocation logic
ci(workflows): add coverage reporting to ubuntu workflow
style: apply clang-format to all source files
test(buffer): add unit tests for buffer manager

❌ Bad commit messages:

update code
Fixed bug
Add feature
WIP
asdf

Scope (Optional but Recommended)

The scope should indicate what part of the codebase is affected:

  • memory - Memory management (buffers, allocators)
  • tensor - Tensor operations
  • model - Model implementation
  • build - Build system (CMake, Conan)
  • ci - CI/CD workflows
  • test - Testing infrastructure
  • docs - Documentation

What Gets Checked

On Every Commit

  1. File checks:

    • Remove trailing whitespace
    • Ensure files end with newline
    • Check for large files (>1MB)
    • Detect merge conflicts
    • Check YAML/JSON syntax
    • Detect private keys

  2. Code formatting:

    • C/C++ files: clang-format
    • CMake files: cmake-format
    • YAML/JSON: prettier
    • Shell scripts: shellcheck
    • Python scripts: black

  3. Commit message:

    • Must follow conventional commit format
    • Type must be from allowed list
    • Subject should be concise

Bypassing Hooks (Not Recommended)

If you absolutely need to skip the hooks (e.g., for a WIP commit):

# Skip pre-commit hooks (file checks)
git commit --no-verify

# Skip commit-msg hook
git commit --no-verify

⚠️ Warning: Bypassed commits will still be checked by CI and may fail!

Updating Hooks

# Update to latest versions
pre-commit autoupdate

# Reinstall hooks after config changes
pre-commit install --hook-type commit-msg --hook-type pre-commit

CI Integration

Pre-commit checks also run in CI (GitHub Actions). If your local hooks pass, CI should pass too.

Troubleshooting

"command not found: pre-commit"

pip install pre-commit

"hook failed" errors

# Run to see detailed error
pre-commit run --all-files

# Reinstall hooks
pre-commit uninstall
pre-commit install --hook-type commit-msg --hook-type pre-commit

Formatting conflicts

# Let pre-commit auto-fix formatting
pre-commit run --all-files

# Stage the auto-fixed files
git add .

# Commit again
git commit -m "style: apply automated formatting"

More Information