Contribuire

GEO Optimizer è open source con licenza MIT. I contributi sono benvenuti -- che si tratti di correggere un bug, aggiungere una funzionalità, migliorare la documentazione o ampliare la copertura dei test.

Repository: github.com/auriti-web-design/geo-optimizer-skill

Configurazione dell'ambiente di sviluppo

Clonare e installare

git clone https://github.com/auriti-web-design/geo-optimizer-skill.git
cd geo-optimizer-skill

# Crea l'ambiente virtuale
python3 -m venv .venv
source .venv/bin/activate

# Installa le dipendenze
pip install -r requirements.txt

# Installa le dipendenze per i test
pip install pytest pytest-cov

Verifica dell'installazione

# Esegui la suite di test
pytest tests/ -v

# Esegui un audit rapido per verificare che gli script funzionino
python scripts/geo_audit.py --url https://example.com

Esecuzione dei test

Suite di test completa

pytest tests/ -v

La suite di test include:

Categoria	Numero	File
Test unitari	67	test_audit.py, test_http_utils.py, test_schema_validator.py
Test di integrazione	13	test_integration.py
Test di validazione	9	test_schema_validator.py
Totale	89

Con report di copertura

pytest tests/ --cov=scripts --cov-report=term-missing -v

Esempio di output:

---------- coverage: platform linux, python 3.12.0 -----------
Name                          Stmts   Miss  Cover   Missing
------------------------------------------------------------
scripts/geo_audit.py            245     32    87%   112-118, 245-260
scripts/generate_llms_txt.py    180     45    75%   ...
scripts/schema_injector.py      210     52    75%   ...
------------------------------------------------------------
TOTAL                           635    129    80%

============ 89 passed in 12.34s ============

Obiettivi di copertura

Metrica	Obiettivo	Attuale
Logica di business	85%+	87%
Copertura totale	70%+	70%
Tutti i test superati	100%	100% (89/89)

Logica di business vs. copertura totale

La copertura della logica di business (87%) misura le funzioni principali di scoring, parsing e generazione. La copertura totale (70%) include la gestione degli argomenti CLI, l'I/O su file e il codice di rete, più difficili da testare in isolamento. Il progetto dà priorità alla copertura della logica di business.

Eseguire file di test specifici

# Solo test dell'audit
pytest tests/test_audit.py -v

# Solo test di integrazione
pytest tests/test_integration.py -v

# Solo test di validazione degli schema
pytest tests/test_schema_validator.py -v

# Solo test delle utility HTTP
pytest tests/test_http_utils.py -v

Eseguire test corrispondenti a un pattern

# Tutti i test relativi a robots.txt
pytest tests/ -v -k "robots"

# Tutti i test relativi all'output JSON
pytest tests/ -v -k "json"

---

Punteggio di qualità

GEO Optimizer tiene traccia di un punteggio di qualità composito su sei dimensioni, valutato su una scala da 0 a 10 con categorie pesate. Lo stesso criterio viene usato per ogni versione per garantire misurazioni coerenti e confrontabili.

Criteri di valutazione

Dimensione	Peso	Cosa misura
Idea e posizionamento	15%	Unicità di mercato, aderenza problema-soluzione
Struttura del codice	20%	Architettura, modularità, standard Python
Documentazione	20%	Qualità del README, esempi, documentazione inline, changelog
Robustezza e testing	25%	Copertura dei test, CI/CD, gestione errori, casi limite
UX e usabilità	10%	Intuitività della CLI, leggibilità dell'output, semplicità di installazione
Potenziale di crescita	10%	Roadmap, estensibilità, predisposizione alla community

Scala dei punteggi

Intervallo	Significato
9,0--10,0	Qualità di riferimento, leader del settore
8,0--8,9	Pronto per la produzione, livello professionale
7,0--7,9	Solido, funzionale, con qualche aspetto da migliorare
6,0--6,9	Utilizzabile ma necessita di miglioramenti
Sotto 6,0	Lavoro significativo necessario

Storico delle versioni

Versione	Data	Punteggio	Modifiche principali
v1.0.0	18-02-2026	7,20	Release iniziale: 3 script, file di contesto AI, documentazione
v1.1.0	21-02-2026	--	CI con GitHub Actions, schema_injector v2 (estrazione automatica FAQ), CONTRIBUTING.md
v1.2.0	21-02-2026	9,20	Formato output JSON, 22 test unitari, 66% di copertura
v1.3.0	21-02-2026	9,40	Logica di retry di rete (backoff esponenziale), 67 test, 87% logica di business
v1.4.0	21-02-2026	9,15	Validazione schema (jsonschema), 13 test di integrazione, integrazione Codecov
v1.5.0	21-02-2026	9,25	Modalità verbose (--verbose), pulizia documentazione, 89 test totali

Criteri coerenti

I criteri di valutazione non cambiano tra le versioni. Come indicato nel documento dei criteri del progetto: "il confronto tra versioni usa gli stessi criteri (nessuno spostamento dei paletti)." Questo garantisce che le variazioni del punteggio riflettano miglioramenti reali.

---

Standard del codice

Stile Python

• Conforme a PEP 8 (verificato con flake8)
• Limite di 120 caratteri per riga (non 79)
• Type hint consigliati per tutte le firme delle funzioni
• Docstring obbligatorie per tutte le funzioni pubbliche

def calculate_score(checks: dict[str, CheckResult]) -> int:
    """Calculate the total GEO score from individual check results.

    Args:
        checks: Dictionary mapping check names to their results.

    Returns:
        Integer score from 0 to 100.
    """
    return sum(check.score for check in checks.values())

Ordine degli import

Segui questa organizzazione, con ordinamento alfabetico all'interno di ogni gruppo:

# 1. Libreria standard
import json
import sys
from pathlib import Path

# 2. Pacchetti di terze parti
import requests
from bs4 import BeautifulSoup

# 3. Import locali
from scripts.geo_audit import run_audit

Messaggi di commit

Segui le Conventional Commits con gli scope specifici del progetto:

feat(audit): add JSON output format
fix(llms): handle malformed XML sitemap gracefully
test(schema): add validation tests for FAQPage
docs(readme): update installation instructions
ci(actions): add Python 3.12 to test matrix

Scope validi: audit, llms, schema, install, docs, ci

---

Processo di pull request

1. Fork e branch

# Fai il fork del repository su GitHub, poi:
git clone https://github.com/YOUR-USERNAME/geo-optimizer-skill.git
cd geo-optimizer-skill
git checkout -b feature/your-feature-name

2. Implementa le modifiche

• Scrivi il codice seguendo gli standard sopra indicati
• Aggiungi test per le nuove funzionalità e le correzioni di bug
• Esegui la suite di test completa per assicurarti che nulla si sia rotto

3. Esegui i controlli di qualità

# Esegui tutti i test
pytest tests/ -v

# Verifica che la copertura non sia diminuita
pytest tests/ --cov=scripts --cov-report=term-missing

# Lint (se flake8 è installato)
flake8 scripts/ --max-line-length=120

4. Aggiorna la documentazione

Quando aggiungi funzionalità, aggiorna i file pertinenti:

Tipo di modifica	File da aggiornare
Nuovo flag di uno script	README.md, pagina pertinente in docs/
Nuova funzionalità	README.md, CHANGELOG.md (sotto [Unreleased])
Correzione di bug	CHANGELOG.md (sotto [Unreleased])
Nuovo contesto AI	SKILL.md, directory ai-context/

5. Push e apertura della PR

git add .
git commit -m "feat(scope): description of the change"
git push origin feature/your-feature-name

Quindi apri una Pull Request su GitHub verso il branch main.

Linee guida per le PR

• Una funzionalità per PR -- mantieni le modifiche focalizzate per una revisione più semplice
• Includi l'output dei test -- incolla il riepilogo di pytest nella descrizione della PR
• Descrivi il "perché" -- spiega quale problema risolve la modifica, non solo cosa è cambiato nel codice
• Collega le issue correlate -- fai riferimento alle issue GitHub con Fixes #123 o Closes #123

Tempi di revisione

I maintainer revisionano le pull request entro 3--5 giorni lavorativi. Potrebbero essere richieste modifiche prima del merge.

---

Roadmap

Funzionalità pianificate per le versioni future (dal CHANGELOG):

• Output in formato HTML -- report di audit visivi per stakeholder non tecnici
• Modalità audit batch -- audit di più URL in una singola esecuzione
• Distribuzione su PyPI -- installazione tramite pip install geo-optimizer
• Workflow GitHub Actions riutilizzabile -- integrazione CI con una sola riga

Se desideri lavorare su una di queste funzionalità, apri prima una issue per discutere l'approccio.

---

Licenza

GEO Optimizer è rilasciato sotto licenza MIT. Contribuendo, accetti che i tuoi contributi siano rilasciati sotto gli stessi termini.