Skip to content

quickstart-with-pre-commit.md

Latest commit

 

History

History
127 lines (89 loc) · 3.43 KB

quickstart-with-pre-commit.md

File metadata and controls

127 lines (89 loc) · 3.43 KB

Adding pre-commit to NEMDataTools

Pre-commit is a fantastic tool that runs checks before each commit, ensuring code quality and consistency. This guide will show you how to integrate pre-commit with your NEMDataTools project, specifically working with UV for dependency management.

Step 1: Update pyproject.toml to include pre-commit

First, add pre-commit to your development dependencies in pyproject.toml:

[project.optional-dependencies]
dev = [
    "pytest>=6.0",
    "pytest-cov>=2.12",
    "black>=25.0.0",
    "mypy>=1.14.0",
    "isort>=6.0.0",
    "pre-commit>=3.3.2",
    "ruff>=0.5.0",
    "commitizen>=4.4.0",
]

Step 2: Install pre-commit using UV

Install the updated development dependencies:

# Make sure your virtual environment is activated
uv pip install -e ".[dev]"

Step 3: Create a pre-commit configuration

Create a .pre-commit-config.yaml file in the root of your project with the configuration provided in the artifacts.

This configuration includes:

  • Basic file checks (YAML, TOML, trailing whitespace, etc.)
  • Code formatting with Black
  • Import sorting with isort
  • Style checking with flake8
  • Type checking with mypy
  • Python upgrades with pyupgrade
  • Commit message formatting with commitizen

Step 4: Install the pre-commit hooks

# Install the pre-commit hooks
pre-commit install

# Also install the commit message hook
pre-commit install --hook-type commit-msg

Step 5: Run pre-commit manually (optional)

You can run pre-commit manually on all files:

pre-commit run --all-files

Using pre-commit with UV

When you need to update pre-commit or its dependencies:

# Update dependencies
uv pip install --upgrade -e ".[dev]"

# Update pre-commit hooks
pre-commit autoupdate

Integration with your development workflow

  1. Local Development: Pre-commit will automatically run before each commit
  2. CI/CD Pipeline: Add pre-commit to your GitHub Actions workflow

Example GitHub Actions step:

- name: Run pre-commit
  run: |
    uv pip install pre-commit
    pre-commit run --all-files

Customizing pre-commit configuration

You can customize the .pre-commit-config.yaml file to suit your needs:

  1. Add hooks: There are many pre-commit hooks available
  2. Adjust parameters: Modify hook arguments to suit your project
  3. Skip hooks: Use SKIP=hook_id git commit to skip specific hooks

Commit message convention with commitizen

The provided configuration includes commitizen, which enforces a standard commit message format. Commits will follow the Conventional Commits specification:

type(scope): description

[optional body]

[optional footer(s)]

Examples:

  • feat: add new downloader function
  • fix(cache): resolve issue with file locking
  • docs: update README with UV instructions

Troubleshooting pre-commit

If you encounter issues:

  1. Hooks failing: Read the error message and fix the issue
  2. Skip hooks temporarily: SKIP=flake8 git commit -m "message"
  3. Update hooks: pre-commit autoupdate
  4. Reinstall hooks: pre-commit uninstall && pre-commit install

Additional Tips

  1. Editor Integration: Many editors have pre-commit plugins
  2. Automated fixes: Most hooks will automatically fix issues when possible
  3. Performance: Some hooks can be slow (like mypy) - you can exclude them for rapid development