Skip to content

Latest commit

 

History

History
280 lines (213 loc) · 6.09 KB

CONTRIBUTING.md

File metadata and controls

280 lines (213 loc) · 6.09 KB

Contributing to ValidKit Python SDK

Thank you for your interest in contributing to ValidKit! We welcome contributions from the community.

Commit Message Convention

We follow Conventional Commits specification for clear and consistent commit history.

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only changes
  • style: Code style changes (formatting, etc)
  • refactor: Code change that neither fixes a bug nor adds a feature
  • perf: Performance improvements
  • test: Adding missing tests or correcting existing tests
  • build: Changes that affect the build system or external dependencies
  • ci: Changes to CI configuration files and scripts
  • chore: Other changes that don't modify src or test files

Examples

feat: add async context manager support

fix: correct timeout handling in batch operations

docs: add async/await examples to README

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct:

  • Be respectful and inclusive
  • Welcome newcomers and help them get started
  • Focus on constructive criticism
  • Respect differing viewpoints and experiences

How to Contribute

Reporting Bugs

  1. Check if the bug has already been reported in Issues
  2. If not, create a new issue with:
    • Clear title and description
    • Steps to reproduce
    • Expected vs actual behavior
    • Python version and OS
    • Relevant code snippets

Suggesting Features

  1. Check if the feature has been requested
  2. Open a new issue with:
    • Clear use case
    • Proposed implementation (if any)
    • Benefits to users

Pull Request Guidelines

Before Creating a PR

  1. Fork the repository and clone locally

  2. Create a feature branch from main:

    git checkout -b feat/your-feature-name
# or
git checkout -b fix/your-bug-fix

  3. Set up your development environment:

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

  4. Make your changes following Python best practices

  5. Write/update tests to maintain coverage

  6. Run all checks:

    pytest
mypy validkit
flake8 validkit
black validkit --check

Commit Your Changes

Follow our commit convention:

# Single line commit
git commit -m "feat: add timeout configuration"

# Multi-line commit with details
git commit -m "feat: add batch result filtering" -m "- Add filter_invalid option to batch results
- Support custom validation rules
- Update type hints for new options
- Add async examples to documentation"

PR Title and Description

Your PR title should follow the same convention as commits:

  • feat: add async generator for streaming results
  • fix: handle connection pool exhaustion
  • docs: add FastAPI integration example
  • perf: optimize memory usage for large batches

In your PR description, include:

## What
Brief description of what this PR does

## Why
The problem it solves or feature it adds
Closes #[issue number]

## How
- Technical approach taken
- Any async/await considerations
- Breaking changes (if any)

## Testing
- Unit tests added/updated
- Async tests included
- Manual testing performed
- Python versions tested

## Checklist
- [ ] Tests pass locally
- [ ] Type hints are correct
- [ ] Code is formatted with Black
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

Example PR Description

## What
Adds support for streaming validation results using async generators

## Why
Large batch validations can consume significant memory
Closes #45

## How
- Implemented AsyncGenerator for result streaming
- Added chunk_size parameter to control memory usage
- Maintains backwards compatibility with list returns

## Testing
- Added async generator tests
- Tested with 100K email batches
- Memory usage reduced by 80%
- Tested on Python 3.8, 3.10, 3.12

## Checklist
- [x] Tests pass locally
- [x] Type hints are correct
- [x] Code is formatted with Black
- [x] Documentation updated
- [x] No breaking changes

After Creating Your PR

  1. Ensure all GitHub Actions checks pass
  2. Respond to code review feedback promptly
  3. Keep your branch up to date with main
  4. Be prepared to make changes based on feedback

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/python-sdk.git
cd python-sdk

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=validkit

# Run specific test file
pytest tests/test_client.py

# Run tests in watch mode
pytest-watch

Code Style

We use:

  • Black for code formatting
  • isort for import sorting
  • flake8 for linting
  • mypy for type checking

Run all checks:

# Format code
black .

# Sort imports
isort .

# Run linter
flake8

# Type check
mypy validkit

Documentation

  • Add docstrings to all public functions/classes
  • Update README.md for user-facing changes
  • Add examples for new features
  • Keep documentation clear and concise

Commit Messages

Follow conventional commits:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • test: Test additions/changes
  • refactor: Code refactoring
  • style: Code style changes
  • chore: Maintenance tasks

Examples:

feat: add webhook support for batch processing
fix: handle rate limit errors correctly
docs: update batch verification examples

Release Process

  1. Update version in pyproject.toml
  2. Update CHANGELOG.md
  3. Create release PR
  4. After merge, tag release: git tag v1.2.3
  5. Push tags: git push --tags
  6. GitHub Actions will publish to PyPI

Questions?

Thank you for contributing! 🎉