Contribuire a gac

December 6, 2025 · View on GitHub

Grazie per il tuo interesse a contribuire a questo progetto! Il tuo aiuto è apprezzato. Per favore segui queste linee guida per rendere il processo fluido per tutti.

Setup Ambiente di Sviluppo

Questo progetto usa uv per la gestione delle dipendenze e fornisce un Makefile per compiti di sviluppo comuni:

Setup Rapido

# Un comando per configurare tutto inclusi gli hook Lefthook
make dev

Questo comando:

Installerà le dipendenze di sviluppo
Installerà gli hook git
Eseguirà gli hook Lefthook su tutti i file per correggere eventuali problemi esistenti

Setup Alternativo (se preferisci passo-passo)

# Crea ambiente virtuale e installa dipendenze
make setup

# Installa dipendenze di sviluppo
make dev

# Installa hook Lefthook
brew install lefthook  # o vedi docs sotto per alternative
lefthook install
lefthook run pre-commit --all

Comandi Disponibili

make setup - Crea ambiente virtuale e installa tutte le dipendenze
make dev - Setup di sviluppo completo - include hook Lefthook
make test - Esegui test standard (esclude test di integrazione)
make test-integration - Esegui solo test di integrazione (richiede chiavi API)
make test-all - Esegui tutti i test
make test-cov - Esegui test con report di coverage
make lint - Controlla qualità del codice (ruff, prettier, markdownlint)
make format - Correggi automaticamente problemi di formattazione del codice

Incremento Versione

Importante: Le PR dovrebbero includere un incremento di versione in src/gac/__version__.py quando contengono modifiche che dovrebbero essere rilasciate.

Come incrementare la versione

Modifica src/gac/__version__.py e incrementa il numero di versione
Segui Semantic Versioning:
- Patch (1.6.X): Correzioni di bug, piccoli miglioramenti
- Minor (1.X.0): Nuove funzionalità, modifiche retrocompatibili (es: aggiungere un nuovo provider)
- Major (X.0.0): Modifiche breaking

Processo di Release

Le release sono attivate dal push di tag di versione:

Fonde PR con incrementi di versione su main
Crea un tag: git tag v1.6.1
Push del tag: git push origin v1.6.1
GitHub Actions pubblica automaticamente su PyPI

Esempio:

# src/gac/__version__.py
__version__ = "1.6.1"  # Incrementato da 1.6.0

Usare bump-my-version (opzionale)

Se hai bump-my-version installato, puoi usarlo localmente:

# Per correzioni di bug:
bump-my-version bump patch

# Per nuove funzionalità:
bump-my-version bump minor

# Per modifiche breaking:
bump-my-version bump major

Standard di Codifica

Target Python 3.10+ (3.10, 3.11, 3.12, 3.13, 3.14)
Usa type hints per tutti i parametri di funzione e valori di ritorno
Mantieni il codice pulito, compatto e leggibile
Evita complessità non necessaria
Usa logging invece di istruzioni print
La formattazione è gestita da ruff (linting, formattazione e ordinamento import in uno strumento; lunghezza massima linea: 120)
Scrivi test minimi ed efficaci con pytest

Git Hooks (Lefthook)

Questo progetto usa Lefthook per mantenere i controlli di qualità del codice veloci e consistenti. Gli hook configurati rispecchiano il nostro setup pre-commit precedente:

ruff - Python linting e formattazione (sostituisce black, isort e flake8)
markdownlint-cli2 - Markdown linting
prettier - Formattazione file (markdown, yaml, json)
check-upstream - Hook personalizzato per controllare modifiche upstream

Setup

Approccio raccomandato:

make dev

Setup manuale (se preferisci passo-passo):

Installa Lefthook (scegli l'opzione che corrisponde al tuo setup):

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

Installa gli hook git:
```
lefthook install
```
(Opzionale) Esegui su tutti i file:
```
lefthook run pre-commit --all
```

Gli hook ora eseguiranno automaticamente a ogni commit. Se qualche controllo fallisce, dovrai correggere i problemi prima di poter fare il commit.

Saltare Git Hooks

Se hai bisogno di saltare temporaneamente i controlli Lefthook, usa il flag --no-verify:

git commit --no-verify -m "Il tuo messaggio di commit"

Nota: Questo dovrebbe essere usato solo quando assolutamente necessario, poiché bypassa controlli importanti di qualità del codice.

Linee Guida per i Test

Il progetto usa pytest per i test. Quando aggiungi nuove funzionalità o correggi bug, per favore includi test che coprono le tue modifiche.

Nota che la directory scripts/ contiene script di test per funzionalità che non possono essere facilmente testate con pytest. Sentiti libero di aggiungere script qui per testare scenari complessi o test di integrazione che sarebbero difficili da implementare usando il framework pytest standard.

Eseguire i Test

# Esegui test standard (esclude test di integrazione con chiamate API reali)
make test

# Esegui solo test di integrazione provider (richiede chiavi API)
make test-integration

# Esegui tutti i test inclusi test di integrazione provider
make test-all

# Esegui test con coverage
make test-cov

# Esegui file di test specifico
uv run -- pytest tests/test_prompt.py

# Esegui test specifico
uv run -- pytest tests/test_prompt.py::TestExtractRepositoryContext::test_extract_repository_context_with_docstring

Test di Integrazione Provider

I test di integrazione provider fanno chiamate API reali per verificare che le implementazioni dei provider funzionino correttamente con le API effettive. Questi test sono marcati con @pytest.mark.integration e sono saltati di default per:

Evitare di consumare crediti API durante lo sviluppo regolare
Prevenire fallimenti dei test quando le chiavi API non sono configurate
Mantenere l'esecuzione dei test veloce per iterazione rapida

Per eseguire i test di integrazione provider:

Configura le chiavi API per i provider che vuoi testare:

export ANTHROPIC_API_KEY="tua-chiave"
export CEREBRAS_API_KEY="tua-chiave"
export GEMINI_API_KEY="tua-chiave"
export GROQ_API_KEY="tua-chiave"
export OPENAI_API_KEY="tua-chiave"
export OPENROUTER_API_KEY="tua-chiave"
export STREAMLAKE_API_KEY="tua-chiave"
export ZAI_API_KEY="tua-chiave"
# LM Studio e Ollama richiedono un'istanza locale in esecuzione
# Le chiavi API per LM Studio e Ollama sono opzionali a meno che il tuo deployment non impona autenticazione

Esegui test provider:
```
make test-integration
```

I test salteranno provider dove le chiavi API non sono configurate. Questi test aiutano a rilevare cambiamenti API presto e assicurano compatibilità con le API dei provider.

Per risoluzione problemi, vedi TROUBLESHOOTING.md
Per utilizzo e opzioni CLI, vedi USAGE.md
Per dettagli licenza, vedi ../../LICENSE

Grazie per aiutare a migliorare gac!