BUGFIX

Questa procedura descrive passo per passo come aprire, sviluppare e chiudere un bugfix, in base al modello Gitflow esteso multi-release.

1. Verifica quale versione è affetta dal bug (es. 4.7.9, 4.8.0, ecc.)
2. Decidi su quale linea di manutenzione intervenire:
   • Versione in sviluppo → branch `develop`
   • Versione rilasciata → branch `hotfix/` o `maintenance/`

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..)

• Se il bug è in una release già uscita:
  1. Parti da `maintenance/x.y.x` oppure dall’ultimo tag corrispondente
  2. 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):
  1. Parti dal branch corrispondente
  2. (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]

1. Risolvi il bug nel codice
2. L'intervento va commentato:
   1. in linguaggio naturale, preferibilmente in inglese, per descrivere l'oggetto dell'intervento (opzionale solo i casi triviali tipo null-check)
   2. 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
//-------------
...
//-------------

1. Aggiorna eventualmente i test unitari/integrati
2. Esegui `mvn clean install` per assicurarti che la build sia valida
3. 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]"

1. 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)
2. Su `develop` o `release/`: lascia la versione -SNAPSHOT o -RELEASE corrente

In generale nel gwRegistry ci sono due liste con versioni da tenere allineate:

1. 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]
2. 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

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)

1. (opzionalmente) apri una pull request verso il branch di origine (`hotfix/`, `release/` o `develop`)
2. Una volta approvata:
   • Hotfix:
     1. (opzionalmente, se c'è stata pull request) mergiare su `HOTFIX/4.7.9.X`
     2. Taggare la versione rilasciata (es. `4.7.9.1`)
     3. bump della versione nel pom.xml alla successiva 4.7.9.2-HOTFIX
     4. Mergiare anche su `maintenance/4.7.x` e su `develop` (senza bump nel pom.xml ⇒ verrà aumentato alla prossima release)
     5. Se necessario, backport su altre linee di manutenzione (in dietro solo con cerry-pick)
   • Bugfix su develop/release:
     1. Mergiare solo sul branch corrispondente
     2. Se necessario, backport su altre linee di manutenzione (in dietro solo con cerry-pick)

1. Elimina i branch di bugfix chiusi da locale e remoto:

git branch -d bugfix/issue_10000
git push origin --delete bugfix/issue_10000

1. Comunica al team il nuovo numero di versione disponibile