feat: add pre-commit hooks configuration with pyink and pylint

[samay2504]

Summary

Adds comprehensive pre-commit hooks setup to automate code quality checks and maintain consistent style across contributions. This feature was requested and approved by maintainers in issue #448.

Motivation

From issue #448:

"Adding pre-commit hooks would help contributors catch formatting and linting issues early, reducing CI failures and review iterations."

Benefits:

• Catches formatting issues before commit
• Reduces CI failures and review time
• Ensures consistent code style across all contributions
• Automates adherence to Google Python style guide
• Lowers barrier for new contributors

Changes

1. .pre-commit-config.yaml (NEW)

Comprehensive pre-commit configuration including:

Standard hooks:

• trailing-whitespace: Remove trailing whitespace
• end-of-file-fixer: Ensure files end with newline
• check-yaml/toml/json: Validate config files
• check-added-large-files: Prevent large file commits (>1MB)
• check-merge-conflict: Detect merge conflict markers
• check-case-conflict: Catch case-sensitivity issues
• mixed-line-ending: Normalize line endings to LF
• debug-statements: Prevent debug code commits

Python code formatting (pyink):

• Google's Python formatter based on Black
• Configured with project settings:
  • 80-character line length
  • 2-space indentation
  • Google style guide compliance

Python linting (pylint):

• Uses existing .pylintrc configuration
• Includes necessary dependencies (jax, flax, numpy)
• Enforces Google Python Style Guide

2. CONTRIBUTING.md (UPDATED)

Added comprehensive "Development Environment Setup" section with:

Installation instructions:

• Step-by-step setup guide
• Pre-commit installation commands
• Hook activation instructions

Usage guidelines:

• Automatic execution workflow
• Manual execution commands
• Troubleshooting tips
• Skip instructions (with warnings)

What gets checked:

• Clear explanation of each hook's purpose
• Expected behavior and output
• Fix instructions for common issues

Testing

Pre-commit hooks tested locally:

pre-commit install
pre-commit run --all-files

Results:

• All hooks execute successfully
• Formatting checks pass on existing code
• No false positives from pylint
• Git workflow integration works correctly

Test commands:

# Install hooks
pre-commit install

# Run on all files
pre-commit run --all-files

# Test individual hooks
pre-commit run pyink --all-files
pre-commit run pylint --all-files

Configuration Details

pyink settings (matches pyproject.toml):

- --line-length=80
- --pyink-indentation=2
- --pyink-use-majority-quotes

pylint settings:

• Uses existing .pylintrc
• Additional dependencies for imports: jax, jaxlib, flax, numpy

Impact

• No breaking changes
• Optional for contributors (can skip with --no-verify)
• CI checks still run (safety net)
• Improves contributor experience
• Reduces maintainer review burden

Compatibility

• Requires: Python 3.8+
• Dependencies: pip install pre-commit (documented in CONTRIBUTING.md)
• Git hooks: Compatible with all Git versions
• OS: Cross-platform (Windows, macOS, Linux)

Documentation

• Installation instructions added to CONTRIBUTING.md
• Usage examples provided
• Troubleshooting section included
• Clear explanation of what each hook does

Checklist

• Feature requested and approved by maintainer (@Balakrishna-Chennamsetti)
• Code follows Google Python Style Guide
• All existing tests pass
• Pre-commit hooks tested locally
• Documentation updated
• No breaking changes
• Commit message follows conventional commits format

Future Enhancements

Potential additions for future PRs:

• mypy for static type checking
• isort for import sorting
• bandit for security checks
• Custom hooks for project-specific rules

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.