Contributing

We welcome contributions to KML ORM! This guide will help you get started.

Development Setup

Fork and Clone:

git clone https://github.com/yourusername/kmlorm.git
cd kmlorm

Create Virtual Environment:

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

Install Development Dependencies:
```
pip install -e .[dev]
```
Install Pre-commit Hooks:
```
pre-commit install
```

Code Quality Standards

We maintain high code quality standards:

Type Hints: All functions must have type hints
Docstrings: All public methods must have Google-style docstrings
Testing: All new features must include tests
Code Style: Follow PEP 8 with 100-character line length

Development Tools

Run these commands before submitting:

# Format code
black .
isort .

# Lint code
flake8
pylint kmlorm/

# Type checking
mypy .

# Run tests
pytest

Testing Guidelines

Write tests for all new functionality
Include edge cases and error conditions
Use pytest fixtures for test data
Maintain test coverage above 80%

Test Structure:

class TestNewFeature:
    def test_basic_functionality(self):
        """Test basic feature operation."""
        # Arrange
        kml = KMLFile.from_string(test_kml_data)

        # Act
        result = kml.new_feature()

        # Assert
        assert result is not None

Documentation

Update docstrings for any changed methods
Add examples to docstrings where helpful
Update this documentation if adding new features
Build docs locally to test: cd docs && make html

Submitting Changes

Create Feature Branch:

git checkout -b feature/your-feature-name

Make Changes: Implement your feature with tests

Run Quality Checks:

black . && isort . && flake8 && mypy . && pytest

Commit Changes:

git add .
git commit -m "Add feature: your feature description"

Push and Create PR:

git push origin feature/your-feature-name

Then create a pull request on GitHub.

Release Process

For maintainers:

Update version in pyproject.toml
Update CHANGELOG.md
Create release tag
GitHub Actions will handle PyPI deployment

Getting Help

Issues: Report bugs or request features on GitHub Issues
Discussions: Ask questions in GitHub Discussions
Code Review: All PRs require review before merging

Thank you for contributing to KML ORM!