Skip to content

PRE_COMMIT.md

Latest commit

 

History

History
237 lines (175 loc) · 6.21 KB

PRE_COMMIT.md

File metadata and controls

237 lines (175 loc) · 6.21 KB

Pre-commit Hooks for SurfSense Contributors

Welcome to SurfSense! As an open-source project, we use pre-commit hooks to maintain code quality, security, and consistency across our multi-component codebase. This guide will help you set up and work with our pre-commit configuration.

🚀 What is Pre-commit?

Pre-commit is a framework for managing multi-language pre-commit hooks. It runs automatically before each commit to catch issues early, ensuring high code quality and consistency across the project.

📁 Project Structure

SurfSense consists of three main components:

  • surfsense_backend/ - Python backend API
  • surfsense_web/ - Next.js web application
  • surfsense_browser_extension/ - TypeScript browser extension

🛠 Installation

Prerequisites

  • Python 3.8 or higher
  • Node.js 18+ and pnpm (for frontend components)
  • Git

Install Pre-commit

# Install pre-commit globally
pip install pre-commit

# Or using your preferred package manager
# pipx install pre-commit  # Recommended for isolation

Setup Pre-commit Hooks

  1. Clone the repository:

    git clone https://github.com/masabinhok/SurfSense.git
cd SurfSense

  2. Install the pre-commit hooks:

    pre-commit install

  3. Install commit message hooks (optional, for conventional commits):

    pre-commit install --hook-type commit-msg

🔧 Configuration Files Added

When you install pre-commit, the following files are part of the setup:

  • .pre-commit-config.yaml - Main pre-commit configuration
  • .secrets.baseline - Baseline file for secret detection (prevents false positives)
  • .github/workflows/pre-commit.yml - CI workflow that runs pre-commit on PRs

🎯 What Gets Checked

All Files

  • ✅ Trailing whitespace removal
  • ✅ YAML, JSON, and TOML validation
  • ✅ Large file detection (>10MB)
  • ✅ Merge conflict markers
  • 🔒 Secret detection using detect-secrets

Python Backend (surfsense_backend/)

  • 🐍 Black - Code formatting
  • 📦 isort - Import sorting
  • ⚡ Ruff - Fast linting and formatting
  • 🔍 MyPy - Static type checking
  • 🛡️ Bandit - Security vulnerability scanning

Frontend (surfsense_web/ & surfsense_browser_extension/)

  • 💅 Prettier - Code formatting
  • 🔍 ESLint - Linting (Next.js config)
  • 📝 TypeScript - Compilation checks

Commit Messages

  • 📝 Commitizen - Conventional commit format validation

🚀 Usage

Normal Workflow

Pre-commit will run automatically when you commit:

git add .
git commit -m "feat: add new feature"
# Pre-commit hooks will run automatically

Manual Execution

Run on staged files only:

pre-commit run

Run on specific files:

pre-commit run --files path/to/file.py path/to/file.ts

Run all hooks on all files:

pre-commit run --all-files

⚠️ Warning: Running --all-files may generate numerous errors as this codebase has existing linting and type issues that are being gradually resolved.

Advanced Commands

Update all hooks to latest versions:

pre-commit autoupdate

Run only specific hooks:

pre-commit run black                    # Run only black
pre-commit run --all-files prettier     # Run prettier on all files

Clean pre-commit cache:

pre-commit clean

🆘 Bypassing Pre-commit (When Necessary)

Sometimes you might need to bypass pre-commit hooks (use sparingly!):

Skip all hooks for one commit:

git commit -m "fix: urgent hotfix" --no-verify

Skip specific hooks:

SKIP=mypy,black git commit -m "feat: work in progress"

Available hook IDs to skip:

  • trailing-whitespace, check-yaml, check-json
  • detect-secrets
  • black, isort, ruff, ruff-format, mypy, bandit
  • prettier, eslint
  • typescript-check-web, typescript-check-extension
  • commitizen

🐛 Common Issues & Solutions

Secret Detection False Positives

If detect-secrets flags legitimate content as secrets:

  1. Review the detection - Ensure it's not actually a secret
  2. Update baseline: 
    detect-secrets scan --baseline .secrets.baseline --update
git add .secrets.baseline

TypeScript/Node.js Issues

Ensure dependencies are installed:

cd surfsense_web && pnpm install
cd surfsense_browser_extension && pnpm install

Python Environment Issues

For Python hooks, ensure you're in the correct environment:

cd surfsense_backend
# If using uv
uv sync
# Or traditional pip
pip install -r requirements.txt

Hook Installation Issues

If hooks aren't running:

pre-commit uninstall
pre-commit install --install-hooks

📊 Performance Tips

  • Incremental runs: Pre-commit only runs on changed files by default
  • Parallel execution: Many hooks run in parallel for speed
  • Caching: Pre-commit caches environments to speed up subsequent runs

🔄 CI Integration

Pre-commit also runs in our GitHub Actions CI pipeline on every PR to main. The CI:

  • Runs only on changed files for efficiency
  • Provides the same feedback as local pre-commit
  • Prevents merging code that doesn't pass quality checks

📋 Best Practices

  1. Install pre-commit early in your development setup
  2. Fix issues incrementally rather than bypassing hooks
  3. Update your branch regularly to avoid conflicts with formatting changes
  4. Run --all-files periodically on feature branches (in small chunks)
  5. Keep the .secrets.baseline updated when legitimate secrets-like strings are added

💡 Contributing to Pre-commit Config

To modify the pre-commit configuration:

  1. Edit .pre-commit-config.yaml
  2. Test your changes: 
    pre-commit run --all-files  # Test with caution!
  3. Update the baseline if needed: 
    detect-secrets scan --baseline .secrets.baseline --update
  4. Submit a PR with your changes

🆘 Getting Help

  • Pre-commit docs: https://pre-commit.com/
  • Project issues: Open an issue on GitHub
  • Hook-specific help: Check individual tool documentation (Black, Ruff, ESLint, etc.)

Thank you for contributing to SurfSense! 🏄‍♀️ Quality code makes everyone's surfing experience smoother.