Bijdragen aan gac

December 6, 2025 · View on GitHub

Bedankt voor uw interesse in bijdragen aan dit project! Uw hulp wordt gewaardeerd. Volg deze richtlijnen om het proces voor iedereen soepel te laten verlopen.

Ontwikkelomgeving Instellen

Dit project gebruikt uv voor dependency management en biedt een Makefile voor veelvoorkomende ontwikkeltaken:

Snelle Installatie

# Eén commando om alles in te stellen inclusief Lefthook hooks
make dev

Dit commando zal:

Ontwikkeldependencies installeren
Git hooks installeren
Lefthook hooks uitvoeren op alle bestanden om bestaande problemen op te lossen

Alternatieve Installatie (als u stapsgewijs prefereert)

# Creëer virtuele omgeving en installeer dependencies
make setup

# Installeer ontwikkeldependencies
make dev

# Installeer Lefthook hooks
brew install lefthook  # of zie docs hieronder voor alternatieven
lefthook install
lefthook run pre-commit --all

Beschikbare Commando's

make setup - Creëer virtuele omgeving en installeer alle dependencies
make dev - Volledige ontwikkelinstallatie - inclusief Lefthook hooks
make test - Voer standaard tests uit (exclusief integratietests)
make test-integration - Voer alleen integratietests uit (vereist API sleutels)
make test-all - Voer alle tests uit
make test-cov - Voer tests uit met dekkingsrapport
make lint - Controleer codekwaliteit (ruff, prettier, markdownlint)
make format - Corrigeer code formatteringsproblemen automatisch

Versie Bumping

Belangrijk: PR's moeten een versie bump bevatten in src/gac/__version__.py wanneer ze wijzigingen bevatten die moeten worden uitgebracht.

Hoe de versie te bumpen

Bewerk src/gac/__version__.py en verhoog het versienummer
Volg Semantic Versioning:
- Patch (1.6.X): Bug fixes, kleine verbeteringen
- Minor (1.X.0): Nieuwe features, backwards-compatibele wijzigingen (bv., een nieuwe provider toevoegen)
- Major (X.0.0): Breaking changes

Release Proces

Releases worden getriggerd door het pushen van versietags:

Merge PR(s) met versie bumps naar main
Creëer een tag: git tag v1.6.1
Push de tag: git push origin v1.6.1
GitHub Actions publiceert automatisch naar PyPI

Voorbeeld:

# src/gac/__version__.py
__version__ = "1.6.1"  # Bumped van 1.6.0

Gebruik van bump-my-version (optioneel)

Als u bump-my-version geïnstalleerd heeft, kunt u het lokaal gebruiken:

# Voor bug fixes:
bump-my-version bump patch

# Voor nieuwe features:
bump-my-version bump minor

# Voor breaking changes:
bump-my-version bump major

Coderingsstandaarden

Target Python 3.10+ (3.10, 3.11, 3.12, 3.13, 3.14)
Gebruik type hints voor alle functieparameters en returnwaarden
Houd code schoon, compact en leesbaar
Vermijd onnodige complexiteit
Gebruik logging in plaats van print statements
Formattering wordt afgehandeld door ruff (linting, formattering en import sortering in één tool; maximale lijnlengte: 120)
Schrijf minimale, effectieve tests met pytest

Git Hooks (Lefthook)

Dit project gebruikt Lefthook om codekwaliteitscontroles snel en consistent te houden. De geconfigureerde hooks spiegelen onze vorige pre-commit setup:

ruff - Python linting en formattering (vervangt black, isort en flake8)
markdownlint-cli2 - Markdown linting
prettier - Bestandsformattering (markdown, yaml, json)
check-upstream - Custom hook om upstream wijzigingen te controleren

Installatie

Aanbevolen aanpak:

make dev

Handmatige installatie (als u stapsgewijs prefereert):

Installeer Lefthook (kies de optie die bij uw setup past):

brew install lefthook          # macOS (Homebrew)
# of
cargo install lefthook         # Rust toolchain
# of
asdf plugin add lefthook && asdf install lefthook latest

Installeer de git hooks:
```
lefthook install
```
(Optioneel) Voer uit op alle bestanden:
```
lefthook run pre-commit --all
```

De hooks worden nu automatisch uitgevoerd bij elke commit. Als controles mislukken, moet u de problemen oplossen voordat u commit.

Git Hooks Overslaan

Als u de Lefthook controles tijdelijk moet overslaan, gebruik de --no-verify vlag:

git commit --no-verify -m "Uw commitbericht"

Let op: Dit moet alleen worden gebruikt wanneer het absoluut noodzakelijk is, omdat het belangrijke codekwaliteitscontroles omzeilt.

Test Richtlijnen

Het project gebruikt pytest voor testing. Bij het toevoegen van nieuwe features of het fixen van bugs, voeg tests toe die uw wijzigingen dekken.

Merkt op dat de scripts/ directory testscripts bevat voor functionaliteit die niet gemakkelijk met pytest getest kan worden. Voel vrij om scripts hier toe te voegen voor het testen van complexe scenario's of integratietests die moeilijk te implementeren zouden zijn met het standaard pytest framework.

Tests Uitvoeren

# Voer standaard tests uit (exclusief integratietests met echte API aanroepen)
make test

# Voer alleen provider integratietests uit (vereist API sleutels)
make test-integration

# Voer alle tests uit inclusief provider integratietests
make test-all

# Voer tests uit met coverage
make test-cov

# Voer specifiek testbestand uit
uv run -- pytest tests/test_prompt.py

# Voer specifieke test uit
uv run -- pytest tests/test_prompt.py::TestExtractRepositoryContext::test_extract_repository_context_with_docstring

Provider Integratietests

Provider integratietests doen echte API aanroepen om te verifiëren dat providerimplementaties correct werken met daadwerkelijke API's. Deze tests zijn gemarkeerd met @pytest.mark.integration en worden standaard overgeslagen om:

API credits te vermijden tijdens reguliere ontwikkeling
Testfouten te voorkomen wanneer API sleutels niet geconfigureerd zijn
Testuitvoering snel te houden voor snelle iteratie

Om provider integratietests uit te voeren:

Stel API sleutels in voor de providers die u wilt testen:

export ANTHROPIC_API_KEY="uw-sleutel"
export CEREBRAS_API_KEY="uw-sleutel"
export GEMINI_API_KEY="uw-sleutel"
export GROQ_API_KEY="uw-sleutel"
export OPENAI_API_KEY="uw-sleutel"
export OPENROUTER_API_KEY="uw-sleutel"
export STREAMLAKE_API_KEY="uw-sleutel"
export ZAI_API_KEY="uw-sleutel"
# LM Studio en Ollama vereisen een lokaal instance dat draait
# API sleutels voor LM Studio en Ollama zijn optioneel tenzij uw deployment authenticatie afdwingt

Voer provider tests uit:
```
make test-integration
```

Tests slaan providers over waar API sleutels niet geconfigureerd zijn. Deze tests helpen bij het vroegtijdig detecteren van API wijzigingen en zorgen voor compatibiliteit met provider API's.

Voor probleemoplossing, zie TROUBLESHOOTING.md
Voor gebruik en CLI opties, zie USAGE.md
Voor licentiedetails, zie ../../LICENSE

Bedankt voor het helpen verbeteren van gac!