Contribuire al progetto

XIQUIL e un progetto open source (core in licenza AGPL v3). Ecco come puoi contribuire.

Repository

Il codice sorgente e diviso per responsabilita:

Repository	Contenuto	Quando usarlo
github.com/JustVitLab/xiquil	Core applicativo	Backend, frontend, modelli, API, UI, installazione
xiquil-plugins	Plugin ufficiali	Plugin Marketplace, esempi, packaging .tar.gz
xiquil-wiki	Documentazione	Guide utente, amministrazione, sviluppatori

Il core e distribuito in licenza GNU Affero General Public License v3 (AGPL v3). Il backend e Python/FastAPI/SQLModel; il frontend e TypeScript/React/MUI.

Setup ambiente di sviluppo

1. Clona la repository:

git clone https://github.com/JustVitLab/xiquil.git
cd xiquil

2. Copia il file .env.example in .env e personalizza le variabili
3. Imposta la modalita sviluppo:

APP_TARGET=development
DEBUG=True

4. Avvia:

docker compose up --build

In modalita sviluppo:

• Il frontend usa Vite con Hot Module Replacement (le modifiche si vedono in tempo reale)
• Il backend ha il reload automatico al salvataggio dei file
• Swagger UI e disponibile su https://localhost/api/docs

Per lavorare sui plugin:

1. prepara il plugin nella repo xiquil-plugins;
2. pacchettizza con ./package.sh nome_plugin;
3. abilita PLUGIN_DEVELOPER_MODE=True oppure usa una licenza con plugin_developer=true;
4. installa il .tar.gz da Marketplace plugin > Sviluppatore;
5. riavvia quando richiesto e verifica /api/plugins/{nome_plugin}/ping.

Branching e Pull Request

Branch	Scopo
main	Produzione stabile
beta	Pre-release per testing
develop	Sviluppo attivo

Per contribuire:

1. Crea un fork della repository
2. Crea un branch dal develop: git checkout -b feat/mia-feature develop
3. Implementa le modifiche
4. Fai commit con Conventional Commits:

git commit -m "feat(uscite): aggiungi filtro per categoria"

5. Apri una Pull Request verso develop

Code style

Backend (Python)

• Formattato con ruff
• Type hints dove possibile
• Commenti in inglese
• Entity names in italiano (dominio)

Frontend (TypeScript)

• Lintato con ESLint
• Componenti funzionali con hooks
• MUI per i componenti UI
• Commenti in inglese

Plugin

• Manifest sorgente plugin.source.json per upload Hub; plugin.json runtime generato e firmato dall’Hub
• Metadata, tier, versione pubblica e compatibilità Core si impostano nel form Hub, non nel pacchetto sorgente
• Route FastAPI sotto /api/plugins/{name}
• Tabelle con prefisso plugin_{name}_
• Migrazioni idempotenti in on_startup
• Frontend come frontend/bundle.js senza bundlare React o MUI
• Pacchetti OS dichiarati in system_packages

Come segnalare un bug

1. Vai su github.com/JustVitLab/xiquil/issues
2. Clicca New Issue
3. Usa il template “Bug Report”
4. Includi:
   • Versione di XIQUIL
   • Passi per riprodurre il problema
   • Comportamento atteso vs comportamento effettivo
   • Screenshot se possibile
   • Log rilevanti (docker compose logs app)

Come proporre una feature

1. Apri una Issue con il template “Feature Request”
2. Descrivi il problema che vuoi risolvere
3. Proponi una soluzione
4. Discuti con i maintainer prima di implementare

---

Domande frequenti

Devo firmare un CLA? No. Il progetto e sotto AGPL v3 e non richiede Contributor License Agreement.

Questa regola riguarda le contribuzioni al Core. Pubblicare un artefatto nel Marketplace è un’attività distinta e richiede l’accettazione del Publisher Agreement mostrato dall’Hub. Vedi Diventare Publisher Marketplace.

Posso usare XIQUIL nel mio progetto commerciale? Si, rispettando i termini della licenza AGPL v3: il codice derivato deve essere distribuito con la stessa licenza e il codice sorgente deve essere reso disponibile.

Come posso aiutare senza scrivere codice? Puoi contribuire segnalando bug, proponendo feature, migliorando la documentazione o aiutando altri utenti nelle discussioni.