====== BUGFIX ======
===== Guida pratica: come gestire un bugfix =====
Questa procedura descrive passo per passo come aprire, sviluppare e chiudere un bugfix, in base al modello **Gitflow esteso multi-release**.
===== 1. Identificazione =====
- Verifica **quale versione** è affetta dal bug (es. 4.7.9, 4.8.0, ecc.)
- Decidi su quale linea di manutenzione intervenire:
* Versione in sviluppo → branch `develop`
* Versione rilasciata → branch `hotfix/` o `maintenance/`
===== 2. Creazione della issue su gitlab =====
Per ogni bugfix (ma in generale per ogni intervento) è mandatorio creare una issue di riferimento, nella quale si specificano le seguenti informazioni:
* **titolo** problematica: ci deve essere il nome del componente/feature affetta con una breve descrizione della problematica. Inizialmente si può aprire una issue facendo riferimento a dove si è generato il problema per l'utente finale. Se l'errore per l'utente è fisso e sistematico lo si può citare nel titolo. Se l'errore che ha portato alla prima segnalazione è variabile, o si manifesta in maniere differenti in posti diversi in quanto e causato da una problematica più profonda, è bene citare tale problematica nel titolo (anche modificandolo in seguito).
* **primo commento** problematica: nel commento di apertura della issue bisognerebbe limitarsi alla descrizione della segnalazione originaria e all'errore. Se si ha già chiara cognizione della problematica la si deve esprimere, differenziando tra cause ed effetti. I posti dove si manifesta il bug verranno citati nel primo commento. Altre informazioni da inserire:
* versioni affette (quella di segnalazione + le eventuali altre, appena noto)
* (opzionalmente) documenti di analisi / screenshot
* (opzionalmente) referente che ha segnalato il bug
* (opzionalmente) ambiente particolare dove è stato riscontrato (installazione interna od altro, con indirizzo ed istruzioni)
* (opzionalmente) versioni/milestone dove verrà rilasciato il fix (non tutti i fix vengono sempre riportati in tutte le versioni precedenti). In generali alcuni fix possono essere riportati anche indietro nelle versioni del framework ancora supportate: 4.4.* 4.5.* 4.6.* 4.7.*
* assegnee (uno o più)
* milestone di rilascio: questa corrisponde ad una versione. Dovendo gestire un prodotto multi-release, per convenzione qui va impostata la milestone più vecchia per la quale si intende rilasciare il fix (es: 4.4.31). La convenzione di base è che il fix va propagato a tutte le milestone successive (alcuni team fanno altre issue dedicate per le versioni precedenti/successive, ma noi no). Se per qualche ragione non è cosi (componenti/feature non più esistenti, etc..) questo va specificato nei commenti o tramite le **label** esplicitando le milestone dove propagare il fix (la versione minima supportata è la 4.4.*):
* forwardport-to-4.5.*
* forwardport-to-4.6.*
* forwardport-to-4.7.*
* forwardport-to-4.8.*
* forwardport-to-4.9.*
* tag della issue (bug, toconfirm, confirmed, doing, todo, completed, etc..)
* **successivi commenti**
* si danno maggiori dettagli sulla problematica
* se ci sono documenti di analisi screenshot li si allegano
* se ci sono più soluzione le si descrivono e si spiega il perchè se ne è scelta una in particolare
* se il fix andrebbe anche su vecchie versioni , ma volontariamente non lo si fa si ne si spiega il motivo (troppo oneroso, senza utilizzatori, etc..)
===== .. Creazione del branch =====
* Se il bug è in una release già uscita:
- Parti da `maintenance/x.y.x` oppure dall’ultimo tag corrispondente
- Crea un branch hotfix:
git checkout maintenance/4.7.x
git pull
git checkout -b hotfix/4.7.9.X
* Se il bug riguarda codice non ancora rilasciato (es. su `develop` o un `release/` ancora aperto):
- Parti dal branch corrispondente
- (opzionalmente) apri un branch di fix temporaneo (nel nome del branch ci va la issue e opzionalmente una descrizione):
git checkout develop
git pull
git checkout -b bugfix/issue_10000[:NOME-BUG]
===== 3. Sviluppo =====
- Risolvi il bug nel codice
- L'intervento va commentato:
- in linguaggio naturale, preferibilmente in inglese, per descrivere l'oggetto dell'intervento (opzionale solo i casi triviali tipo null-check)
- **commento della issue di riferimento**, su riga singola o su blocco di modifiche. Questo è molto importante in fase di risoluzione dei conflitti durante i merge. Esempi:
//issue #10000
//issue #10000
//-------------
...
//-------------
- Aggiorna eventualmente i test unitari/integrati
- Esegui `mvn clean install` per assicurarti che la build sia valida
- Fai commit con messaggio chiaro: **in tutti i commit del bugfix deve esserci il riferimento alla issue** (es: issue #10000), magari in prima posizione e seguito dalla descrizione dell'intervento. Utile quando si usano strumenti come //Fork// per capire la corretta propagazione delle issue fra più //branch// Inoltre non sarebbe male riportare brevemente nel corpo del commit l'analisi fatta su gitlab dell'intervento e magari il link della issue su GitLab (questo almeno sul primo/unico commit)
git commit -am "issue #10000 [NOME_COMPONENTE] - [DESCR_FIX]"
===== 4. Versionamento nel pom.xml =====
- Su un branch `hotfix/`: incrementa il quarto numero e usa `-HOTFIX` fino al rilascio
* Esempio: `4.7.9.1-HOTFIX` (al momento del tag 4.7.9.1 nel pom andrebbe messo solo 4.7.9.1, ma per come è la nostra pipeline non è mandatorio)
- Su `develop` o `release/`: lascia la versione -SNAPSHOT o -RELEASE corrente
===== 5. Versioni nel gwRegistry =====
In generale nel gwRegistry ci sono due liste con versioni da tenere allineate:
- **gwVersionList**: versione che deve contenere oltre al fisso 4., solo .[MAJOR].[MINOR] seguito poi da un -[DESCRITTIVO_FUNZIONALE] (-SNAPSHOT, -RELEASE) Viene utilizzato per gestire la migrazione dei metadati => qui NON va esplicitato il quato numero .[FIX]
- **gwVersionToShowList**: versione è destinata alla sola visualizzazione. oltre .[MAJOR].[MINOR] può esserci un .[FIX] nei branch di -hotfix/
L'idea è di seguire le stesse convenzioni della versione del pom.xml, con un unica eccezione per il gwVersionList.
Esempio per bugfix:
in gwVersionList 4.7.9-HOTFIX
in gwVersionToShowList4.7.9.1-HOTFIX
===== 6. Documentazione: Aggiorna il ReleaseNotes =====
Metti una riga nel formato:
* [COMPONENTE] - [problematica risolta] (issue #10000)
La stessa riga va messa in tutti i blocchi di versione dove il fix va rilasciato.
Per facilitare il copia incolla nella wiki e su gitlab:
* meglio lasciare tutto su una sola su una sola riga
* meglio due spazzi bianchi e *, piuttosto che TAB e *
Se è troppo lungo vai su più righe indentando e mettendo sull'ultima riga la issue da sola:
* [COMPONENTE] -
[problematica risolta]
(issue #10000)
Per note complicate sono ammessi sottopunti:
* [COMPONENTE] -
* [problematica risolta 1]
* [problematica risolta 2]
(issue #10000)
===== 7. Merge, Tag e backport =====
- (opzionalmente) apri una pull request verso il branch di origine (`hotfix/`, `release/` o `develop`)
- Una volta approvata:
* **Hotfix**:
- (opzionalmente, se c'è stata pull request) mergiare su `HOTFIX/4.7.9.X`
- Taggare la versione rilasciata (es. `4.7.9.1`)
- bump della versione nel pom.xml alla successiva 4.7.9.2-HOTFIX
- Mergiare anche su `maintenance/4.7.x` e su `develop` (senza bump nel pom.xml => verrà aumentato alla prossima release)
- Se necessario, backport su altre linee di manutenzione (in dietro solo con cerry-pick)
* **Bugfix su develop/release**:
- Mergiare solo sul branch corrispondente
- Se necessario, backport su altre linee di manutenzione (in dietro solo con cerry-pick)
===== 7. Pulizia =====
- Elimina i branch di bugfix chiusi da locale e remoto:
git branch -d bugfix/issue_10000
git push origin --delete bugfix/issue_10000
===== 8. Notifica il Team=====
- Comunica al team il nuovo numero di versione disponibile