Contributing

We welcome contributions to naamkaran! This document provides guidelines for contributing to the project.

Development Setup

  1. Fork and Clone

    Fork the repository on GitHub and clone your fork:

    git clone https://github.com/YOUR_USERNAME/naamkaran.git
cd naamkaran

  2. Create Virtual Environment

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

  3. Install Development Dependencies

    pip install -e ".[dev,test]"

  4. Install Pre-commit Hooks

    pre-commit install

Code Style

We use several tools to maintain code quality:

  • Black for code formatting

  • isort for import sorting

  • flake8 for linting

  • mypy for type checking

Run these tools before committing:

# Format code
black naamkaran/

# Sort imports
isort naamkaran/

# Lint code
flake8 naamkaran/

# Type check
mypy naamkaran/

Or run all at once:

pre-commit run --all-files

Testing

We use pytest for testing. Run tests with:

# Run all tests
pytest

# Run with coverage
pytest --cov=naamkaran

# Run specific test file
pytest naamkaran/tests/test_010_gen_names.py

Write tests for new features and ensure existing tests pass.

Documentation

Documentation is built with Sphinx. To build docs locally:

cd docs
make html

The built documentation will be in docs/build/html/.

For new features, please:

  • Add docstrings to functions and classes

  • Update relevant documentation files

  • Add examples if appropriate

Pull Request Process

  1. Create a Branch

    Create a new branch for your feature or bugfix:

    git checkout -b feature/your-feature-name

  2. Make Changes

    • Write clear, focused commits

    • Follow the code style guidelines

    • Add tests for new functionality

    • Update documentation as needed

  3. Test Your Changes

    # Run tests
pytest --cov=naamkaran

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

# Test documentation build
cd docs && make html

  4. Submit Pull Request

    • Push your branch to GitHub

    • Create a pull request with a clear description

    • Reference any related issues

Pull Request Guidelines

  • Title: Use a clear, descriptive title

  • Description: Explain what changes you made and why

  • Tests: Include tests for new features

  • Documentation: Update docs for user-facing changes

  • Backwards Compatibility: Avoid breaking changes when possible

Example PR description:

## Summary
Add support for generating names with custom length ranges

## Changes
- Added min_len parameter to generate_names function
- Updated CLI to accept --min-len argument
- Added tests for length range validation
- Updated documentation with examples

## Breaking Changes
None

## Testing
- Added test_length_range_validation
- All existing tests pass

Reporting Issues

When reporting bugs or requesting features:

  1. Search existing issues first

  2. Use issue templates when available

  3. Provide clear reproduction steps for bugs

  4. Include environment details (Python version, OS, etc.)

Types of Contributions

We welcome various types of contributions:

Bug Fixes

Fix issues in existing functionality

New Features

Add new capabilities to the library

Documentation

Improve or expand documentation

Tests

Add or improve test coverage

Performance

Optimize existing code

Examples

Add usage examples and tutorials

Release Process

Releases are handled by maintainers:

  1. Update version in pyproject.toml

  2. Update CHANGELOG.md

  3. Create release tag

  4. GitHub Actions automatically publishes to PyPI

Community Guidelines

  • Be respectful and inclusive

  • Help others learn and grow

  • Focus on constructive feedback

  • Follow the code of conduct

Getting Help

If you need help:

  • Check the documentation

  • Search existing issues

  • Ask questions in discussions

  • Reach out to maintainers

Thank you for contributing to naamkaran!