custom:development_bugfix_best_practices [GeowebFramework]

Questa pagina è in sola lettura. Puoi visualizzare il sorgente, ma non puoi modificarlo. Contatta l'amministratore se pensi che ci sia un errore.
====== 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:
<code bash>
git checkout maintenance/4.7.x
git pull
git checkout -b hotfix/4.7.9.X
</code>
  * 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):
<code bash>
git checkout develop
git pull
git checkout -b bugfix/issue_10000[:NOME-BUG]
</code>

===== 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:
<code java>//issue #10000</code> 
<code java>
//issue #10000
//-------------
...
//-------------
</code>
  - 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)
<code bash>
git commit -am "issue #10000 [NOME_COMPONENTE] - [DESCR_FIX]"
</code>

===== 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:
<code>
in gwVersionList 4.7.9-HOTFIX
in gwVersionToShowList4.7.9.1-HOTFIX
</code>


===== 6. Documentazione: Aggiorna il ReleaseNotes =====

Metti una riga nel formato:
<code>
  * [COMPONENTE] - [problematica risolta] (issue #10000)
</code>

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:
<code>
  * [COMPONENTE] - 
    [problematica risolta]
    (issue #10000)
</code>

Per note complicate sono ammessi sottopunti:
<code>
  * [COMPONENTE] - 
    * [problematica risolta 1]
    * [problematica risolta 2]
    (issue #10000)
</code>



===== 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:
<code bash>
git branch -d bugfix/issue_10000
git push origin --delete bugfix/issue_10000
</code>

===== 8. Notifica il Team=====
  - Comunica al team il nuovo numero di versione disponibile