Contributing to QuranKit¶
Thank you for your interest in contributing to QuranKit! This guide covers our development workflow, coding standards, and contribution process.
Development Setup¶
Prerequisites¶
- Python 3.12+
- Git
- pip
Clone and Install¶
git clone https://github.com/AdakHaddad/qurankit.git
cd qurankit
# Create virtual environment
python -m venv .venv
source .venv/bin/activate
# Install in development mode with all extras
pip install -e ".[dev,cli,tanzil,qac,mcp]"
Verify Setup¶
# Run tests
pytest tests/ -v
# Check code style
ruff check src/
ruff format src/ --check
# Type checking
mypy src/
Coding Standards¶
Python Style¶
- Formatter: Ruff (configured in
pyproject.toml) - Line length: 100 characters
- Quotes: Double quotes
- Type hints: Required for all public functions
- Docstrings: Google style
Type Hints¶
# Good
def search_text(query: str, mode: SearchMode = "broad", limit: int = 100) -> list[SearchResult]:
...
# Avoid
def search_text(query, mode="broad", limit=100):
...
Docstrings¶
def lookup_root(self, root_form: str, limit: int | None = None) -> list[VocabularyOccurrence]:
"""Look up all Qur'anic occurrences of an Arabic root.
Args:
root_form: The Arabic root (e.g., "ر ح م" or "رَحْمَة").
limit: Maximum number of occurrences to return.
Returns:
List of vocabulary occurrences sorted by surah/ayah.
Raises:
DatasetNotFoundError: If QAC morphology data is not installed.
"""
Imports¶
# Standard library first
import json
from pathlib import Path
from typing import Optional
# Third-party
import pydantic
from pydantic import BaseModel
# Local
from qurankit.models import Surah
from qurankit.search import SearchEngine
Testing Requirements¶
Test Categories¶
| Category | Location | Purpose |
|---|---|---|
| Unit | tests/unit/ |
Individual functions/classes |
| Integration | tests/integration/ |
Dataset loaders, pipelines |
| Golden | tests/fixtures/ |
Reviewed Arabic examples |
Writing Tests¶
# tests/unit/test_my_feature.py
import pytest
from qurankit import Quran
from qurankit.models import Surah
class TestMyFeature:
def test_surah_creation(self):
surah = Surah(number=1, name_arabic="الفاتحة", ...)
assert surah.number == 1
assert surah.name_arabic == "الفاتحة"
@pytest.fixture
def quran_with_data(self):
# Use fixture for integration tests
quran = Quran.load()
return quran
def test_search_returns_results(self, quran_with_data):
results = quran_with_data.search("بسم الله", mode="broad")
assert len(results) > 0
Arabic Test Fixtures¶
- Use real Qur'anic text from installed datasets
- Never fabricate Arabic text
- Preserve source representation exactly
- Document fixture source and version
# tests/fixtures/arabic_examples.py
# Source: Tanzil Simple v1.0.0
FATIHAH_AYAH_1 = "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ"
FATIHAH_AYAH_1_NORMALIZED_BROAD = "بسم الله الرحمن الرحيم"
Running Tests¶
# All tests
pytest tests/ -v
# Unit only
pytest tests/unit/ -v
# Integration only
pytest tests/integration/ -v
# With coverage
pytest tests/ --cov=qurankit --cov-report=html
# Specific test
pytest tests/unit/test_search.py::TestNormalizationEngine::test_broad_search -v
Git Workflow¶
Branch Naming¶
| Type | Pattern | Example |
|---|---|---|
| Feature | feat/<description> |
feat/add-tafsir-adapter |
| Bugfix | fix/<description> |
fix/search-offset-bug |
| Docs | docs/<description> |
docs/update-api-reference |
| Refactor | refactor/<description> |
refactor/vocabulary-caching |
Commit Messages¶
Follow Conventional Commits:
feat: add tafsir adapter interface
- Add TafsirAdapter abstract base class
- Implement FileBasedTafsirAdapter
- Add registry for multiple tafsir sources
- Include sample data from public domain sources
Closes #123
Pull Request Process¶
- Create feature branch from
main - Implement changes with tests
- Run full test suite:
pytest tests/ -v - Run linting:
ruff check src/andruff format src/ --check - Run type checking:
mypy src/ - Update documentation if needed
- Submit PR with description of changes
- Address review feedback
- Squash and merge (maintainers)
Documentation Standards¶
When to Update Docs¶
- New public API → Update API reference
- New feature → Add user guide page
- Behavior change → Update relevant guides
- New dataset → Update dataset evaluation
Documentation Style¶
- Use clear, concise language
- Include code examples for all features
- Document parameters, returns, exceptions
- Note limitations and known issues
- Use admonitions for warnings/notes
!!! note "Important"
This feature requires QAC morphology data.
!!! warning "License"
QAC data has non-commercial restrictions.
Data and Licensing¶
Adding Datasets¶
- Verify license — Confirm redistribution rights
- Document provenance — Source, version, retrieval date
- Create manifest — Include checksum, license, metadata
- Build adapter — Transform to QuranKit schema
- Add validation — Verify structure and integrity
- Write tests — Golden tests for known references
Arabic Text Handling¶
- Never modify source Arabic text
- Store normalized forms separately
- Track character mappings
- Document normalization rules
- Test edge cases (hamza, alif maqsurah, etc.)
Release Process¶
Versioning¶
Semantic versioning (MAJOR.MINOR.PATCH):
- MAJOR: Breaking API changes
- MINOR: New features, backward compatible
- PATCH: Bug fixes, backward compatible
Release Checklist¶
- All tests pass
- Linting clean
- Type checking clean
- Documentation updated
- Changelog updated
- Version bumped in
pyproject.toml - Tag created:
git tag v0.x.y - Published to PyPI
- GitHub release created
Code of Conduct¶
- Be respectful and inclusive
- Focus on technical merit
- Respect religious sensitivities
- Follow Islamic etiquette for Qur'anic content
- No proselytizing or theological debates in technical discussions
Getting Help¶
- GitHub Issues: Bug reports, feature requests
- GitHub Discussions: Questions, design discussions
- Email: muqtada@example.com
Recognition¶
Contributors are recognized in:
- CONTRIBUTORS.md
- Release notes
- Documentation credits