Quartz 4

FIRE 60.04 - CONTRIBUTING

8 min read

Versione 1.6

FIRE - CONTRIBUTING

Regola 1. Codice Completo e Contestualizzato

1.1 È preferibile lavorare con i file completi e integrali, in modo da poter vedere le modifiche nel loro contesto. Quando apporti modifiche a un file, fornisci l’intero contenuto aggiornato, accompagnato da commenti chiari che evidenzino cosa è stato modificato.

1.2 in alcuni casi hai più file da modificare, scrivi il primo file, poi al termine mi chiedi : quando vuoi proseguo con il prossimo” in modo che aggiorni un solo file alla volta, ovviamente tienimi aggiornato sui file che mancano di volta in volta

1.3 il codice deve essere formattato per essere copiato agevolmente

1.4 non scrivere: ”# … (invariato)” indicando che questa parte del codice resta la stessa quando scrivi il codice completo.

Regola 2. Modularità del Codice

2.1 Prediligo lavorare con più file o moduli piccoli e ben suddivisi, piuttosto che con file molto lunghi e complessi. Questo è per me un aspetto fondamentale.

Regola 3. Sincronizzazione dei File

3.1 Non modifico mai un file senza che tu ne sia a conoscenza. Perciò, non chiedermi file di cui possiedi già una versione aggiornata. In caso di dubbio, chiedimi pure: meglio una domanda in più che un’informazione mancante.

3.2 tieni traccia delle versioni dei file e se devi chiedere un file chiedi anche il numero di versione

Regola 4. Versioning dei File

È importante che la prima riga di ogni file modificato sia un commento strutturato con il percorso, il nome del file e la versione. - La seconda riga conterrà la data dell’ultima modifica.

**Esempio per Python (.py):**

codePython

```
# backend/server.py - v1.4.0
# Ultima modifica: 2024-08-30 10:00
```

**Esempio per C# (.cs) o XAML (.xaml):**

codeC#

```
// ViewModels/LaunchViewModel.cs - v1.3.0
// Ultima modifica: 2024-08-30 10:00
```

codeXml

```
<!-- Views/LaunchView.xaml - v1.2.0 -->
<!-- Ultima modifica: 2024-08-30 10:00 -->
```

Regola 5 Termini

5.1 se uso dei termini sbagliati correggimi, questo mi aiuta a migliorare il mio linguaggio tecnico in modo da essere più preciso in futuro con le richieste

Regola 6 Gestione dei bug:

  • 6.1 L’applicazione è fragile: prima di modificare il codice, analizza attentamente le parti coinvolte per evitare regressioni o dipendenze rotte.
  • 6.2 Puoi fare refactoring se necessario, ma sempre con un’analisi preventiva accurata.
  • 6.3 Dopo due tentativi di fixing falliti, fermati e chiedi aiuto.
  • 6.4 Verifica se esistono versioni precedenti o backup del codice dove il bug non si presenta: possono essere un buon punto di partenza.

Regola 7 Comprensione delle richieste che ti vengono fornite:

7.1 prima di iniziare una attività per favore conferma se ho scritto in modo chiaro e comprensibile prima di procedere, Questo è l’approccio giusto per evitare malintesi.

7.2 Se stiamo già lavorando su un piano d’azione che è stato approvato, al termine di un task anticipami cosa ti serve per il prossimo senza che sono io a chiederti, o se hai finito. procediamo con il commit

Regola 8 Fornitura del Comando Git Completo: 

8.1 Ogni volta che viene suggerito un commit, fornirò il comando git commit completo e pronto per essere copiato e incollato, inclusi i flag necessari (come -m) e il messaggio formattato correttamente.

Regola 9: Principio di Minima Sorpresa (Preservazione del Comportamento Esistente)

9.1. Quando modifico un file per implementare una richiesta, il mio obiettivo è di alterare esclusivamente la logica e l’aspetto necessari per soddisfare quella specifica richiesta.

Piano d’azione dettagliato

Dobbiamo definire un piano che scomponga il problema in passi logici, ognuno testabile individualmente, per minimizzare i rischi e avere sempre il controllo del processo.

Regola 10: Delta delle Righe di Codice (Controllo Incrociato)

10.1 Obbligo di Segnalazione del Delta:
Ogni volta che viene modificato un file già esistente, insieme al file aggiornato deve essere fornita anche un’indicazione del numero di righe aggiunte e rimosse rispetto alla versione precedente.

L’indicazione deve essere nella forma:
+X / -Y (righe aggiunte / righe rimosse)

10.2 Posizionamento della Nota:
La nota sul delta va fornita subito prima del blocco di codice completo del file aggiornato, oppure come breve riga introduttiva nel messaggio di risposta.

10.3 Esempio di Segnalazione:

Delta modifiche: +23 / -5

# backend/server.py - v1.5.0
# Ultima modifica: 2025-09-26 15:45

... (contenuto completo del file aggiornato)

10.4 Obiettivo:

  • Garantire un controllo incrociato per evitare omissioni o dimenticanze.
  • Offrire trasparenza e tracciabilità dell’impatto di ogni modifica.
  • Aiutare nel confronto tra versioni diverse dello stesso file.

10.5 Precisione:
Il conteggio delle righe deve essere esatto (non approssimativo), preferibilmente ottenuto con git diff --stat o strumenti equivalenti.

10.6 Casi Speciali:

  • Nei refactoring estesi, dove molte righe vengono spostate senza modifiche logiche, va comunque riportato il conteggio preciso.
  • Se il file è nuovo, si indica solo +N (righe aggiunte).
  • Se il file viene rimosso, si indica solo -N (righe rimosse).
Nota Operativa

Per rendere semplice e affidabile la pratica:

  • Prima di fornire un file aggiornato, si esegue:
git diff --stat

oppure

git diff --numstat
  • Si copia il risultato relativo al file in questione e lo si include come nota.

Sezione 2: Linee Guida per l’Uso di Git

Queste linee guida si aggiungono alle Regole Generali e hanno lo scopo di utilizzare il sistema di controllo versione Git per migliorare l’organizzazione e la tracciabilità del nostro lavoro, senza sostituire le pratiche esistenti.

2.1. Organizzazione del Lavoro con i Branch

  • 2.1.1. Un Branch per Ogni Obiettivo: Ogni attività di sviluppo distinta (es. implementare una nuova funzionalità, correggere un bug, testare una soluzione) verrà realizzata in un branch separato.
  • 2.1.2. Scopo dei Branch: I branch servono a isolare le modifiche. Questo ci permette di lavorare su diverse soluzioni in parallelo senza che interferiscano tra loro e di confrontarle facilmente. Il branch principale (main) conterrà sempre la versione più stabile e approvata del codice.
  • 2.1.3. Verifica Preliminare del Branch (Regola “Mai su Main”): Prima di scrivere o modificare anche una singola riga di codice, è un passaggio obbligatorio verificare su quale branch ci si trova. Il lavoro di sviluppo non deve mai avvenire direttamente sul branch main.
    • Comando di Verifica: Eseguire il comando git status. La prima riga dell’output confermerà il branch attivo (es. On branch feature/nome-task).
    • Azione Correttiva: Se l’output mostra On branch main, è necessario creare e spostarsi su un nuovo branch (git checkout -b tipo/nome-task) prima di iniziare a lavorare.

2.2. Salvataggio delle Modifiche con i Commit

  • 2.2.1. Commit Atomici: Un “commit” è un salvataggio permanente delle modifiche. Effettueremo un commit al termine di ogni passaggio logico e autoconsistente (es. dopo aver modificato un file per implementare una specifica ottimizzazione).
  • 2.2.2. Messaggi di Commit Chiari: Ogni commit sarà accompagnato da un messaggio descrittivo. Io ti fornirò un messaggio di commit suggerito per ogni blocco di lavoro. Questo crea una cronologia del progetto chiara e leggibile, che funziona come un diario di sviluppo automatico.
    • Esempio di messaggio suggerito: feat(renderer): Implementa parsing con early exit.

2.3. Git come Strumento di Verifica e Sicurezza

  • 2.3.1. “Rete di Sicurezza”: Mentre il versioning manuale nei file (Regola 4) resta il nostro riferimento rapido, Git funge da nostra “rete di sicurezza”. La cronologia dei commit è la fonte di verità assoluta e immutabile di ogni cambiamento avvenuto.
  • 2.3.2. Verifica dello Stato: Se mai avessimo dubbi sullo stato di sincronizzazione del progetto, useremo comandi semplici come git status (per vedere le modifiche correnti) e git log (per vedere gli ultimi salvataggi) per avere una conferma oggettiva e risolvere ogni incertezza.

Guida allo Sviluppo (CONTRIBUTING.md)

Questo documento descrive le pratiche di sviluppo e le convenzioni di versioning per il progetto Whiteboard Generator Q.

1. Workflow Principale con Git

Ogni nuovo sviluppo deve seguire questo flusso per garantire coerenza e isolamento:

  1. Sincronizza il branch main: Assicurati di avere la versione più recente del progetto. 
    git checkout main
git pull origin main
  2. Crea un nuovo branch: Crea un branch dedicato al tuo task, partendo da main. Usa la convenzione tipo/nome-breve-del-task (es. feature/user-login, fix/rendering-bug). 
    git checkout -b feature/nome-task
  3. Sviluppa e Fai Commit: Lavora sul tuo codice. Fai commit piccoli e atomici.
  4. Apri una Pull Request (PR): Quando il tuo lavoro è completo, invia il tuo branch al repository remoto e apri una Pull Request verso main. La PR deve includere una descrizione delle modifiche.
  5. Code Review e Merge: Almeno un altro membro del team deve revisionare la PR. Una volta approvata, verrà integrata (merge) in main.

2. Regole per i Commit

  • Commit Atomici: Ogni commit deve rappresentare una singola modifica logica.
  • Messaggi Chiari: I messaggi di commit devono seguire una convenzione (es. Conventional Commits). Esempio:
    • feat(renderer): Aggiunge il motore di rendering nativo
    • fix(preview): Corregge il bug delle proporzioni SVG

3. Versioning dei File (Pratica Ibrida)

Per facilitare la navigazione nel codice, adottiamo un sistema ibrido:

  • Fonte di Verità Assoluta: Git è la fonte di verità definitiva. La cronologia dei commit e i tag di Git (v1.0, v1.1, ecc.) rappresentano lo stato ufficiale del progetto.
  • Convenzione nei File (Regola 4 Mantenuta): Come convenzione di team, continuiamo ad aggiornare il commento di versione in cima a ogni file modificato. Questo serve come riferimento rapido durante lo sviluppo.
    • # [path]/file.py - vX.Y.Z
    • # Ultima modifica: AAAA-MM-GG HH:MM
  • In Caso di Conflitto: Se il commento in un file non corrisponde alla cronologia di Git, la cronologia di Git ha sempre la precedenza.

4. Altre Linee Guida (Regole 1, 2, 5)

  • Modularità del Codice: Il codice deve essere organizzato in moduli piccoli e con responsabilità chiare.
  • Stile del Codice: Seguire le convenzioni di stile definite per il progetto (es. PEP 8 per Python).
  • Comunicazione: Usare un linguaggio tecnico preciso.

Graph View