Contributing¶

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

Development Setup¶

Fork and Clone

Fork the repository on GitHub and clone your fork:

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

Create Virtual Environment

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

Install Development Dependencies
```
pip install -e ".[dev,test]"
```
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¶

Create a Branch

Create a new branch for your feature or bugfix:
```
git checkout -b feature/your-feature-name
```
Make Changes
- Write clear, focused commits
- Follow the code style guidelines
- Add tests for new functionality
- Update documentation as needed

Test Your Changes

# Run tests
pytest --cov=naamkaran

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

# Test documentation build
cd docs && make html

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:

Search existing issues first
Use issue templates when available
Provide clear reproduction steps for bugs
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:

Update version in pyproject.toml
Update CHANGELOG.md
Create release tag
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!