laboratori-cloud/CONTRIBUTING.md

Contributing al Corso Lab Soluzioni Cloud

Grazie per il tuo interesse a contribuire a questo progetto didattico!

Come Contribuire

Segnala Bug

Trovi un errore nel materiale didattico o negli script?

1. Controlla se il bug è già stato segnalato nelle issue
2. Apri una nuova issue con:
   • Titolo chiaro che descrive il problema
   • Passi per riprodurre il bug
   • Comportamento atteso vs comportamento reale
   • Ambienti e versioni (OS, Docker version)

Suggerisci Miglioramenti

Hai idee per migliorare il corso?

1. Apri una issue con la tua proposta
2. Descrivi il beneficio per gli studenti
3. Suggerisci come implementare il miglioramento

Pull Request

Vuoi contribuire direttamente?

1. Fai fork del repository
2. Crea un branch per il tuo lavoro: git checkout -b feature/tua-feature
3. Fai commit dei tuoi cambi seguendo Conventional Commits
4. Push nel tuo fork e apri una Pull Request

Conventional Commits

Usiamo Conventional Commits per chiarezza:

<tipo>(<ambito>): <descrizione>

[corpo opzionale]

[piè di pagina opzionale]

Tipi

• feat: Nuova funzionalità
• test: Test o verifica
• docs: Documentazione
• fix: Bug fix
• refactor: Refactoring
• chore: Manutenzione variazione

Ambiti

• lab-01, lab-02, etc.: Laboratorio specifico
• integration: Test di integrazione
• docs: Documentazione generale
• scripts: Script di utilità

Esempi

feat(lab-03): add healthcheck monitoring
test(lab-05): verify database isolation
docs(readme): update quick start guide
fix(lab-02): resolve network configuration bug

Linee Guida per il Codice

Script Bash

• Usa set -euo pipefail per error handling
• Aggiungi commenti per logica complessa
• Usa funzioni per codice riutilizzabile
• Rendi gli script eseguibili: chmod +x script.sh

Docker Compose

• Segui la struttura dei lab esistenti
• Rispetta i requisiti INF-01/02/03/04
• Aggiungi commenti per configurazioni complesse
• Includi healthcheck dove appropriato

Documentazione

Segui il framework Diátaxis:

1. Tutorial: Guida passo-passo incrementale
2. How-to: Procedure specifiche e task-focused
3. Reference: Specifiche tecniche nude e crude
4. Explanation: Concetti e parallelismi

Struttura dei File

labs/<lab-name>/
├── tutorial/           # Tutorial passo-passo
├── how-to-guides/      # Guide procedure specifiche
├── reference/          # Specifiche tecniche
├── explanation/        # Concetti e parallelismi
├── tests/              # Script di test
├── docker-compose.yml  # Infrastruttura
└── Dockerfile          # Immagine custom (se necessaria)

Testing

Prima di inviare una PR:

1. Esegui i test del lab: cd labs/<lab-name>/tests && ./run-all-tests.sh
2. Esegui i test di integrazione: cd tests/integration && ./99-final-integration-test.sh
3. Verifica che la documentazione sia completa
4. Testa su ambienti diversi se possibile

Stile di Scrittura

• Usa un tono diretto e semplice
• Evita jargon non necessario
• Spiega i concetti con esempi pratici
• Includi parallelismi con cloud dove appropriato

Review Process

1. Le PR vengono revisionate dal maintainer
2. Richieste di modifiche comuni
3. Approvazione e merge

Domande?

Contatta: luca@lucasacchi.net

---

Grazie per il tuo contributo al corso!