Gestione delle issue

Questa pagina è scritta per chi aiuta nella gestione delle issue sul tracker delle issue di Github.

Premessa

• Qualsiasi progetto ha risorse limitate, la differenza tra i progetti sarà la soglia.
• Qualsiasi progetto dovrebbe avere obiettivi chiari. Per Ansel, è gestire, modificare ed esportare raccolte di immagini RAW su un computer desktop da parte di un utente finale che non usa la CLI ma antepone la qualità visiva dell’immagine a tutto il resto.
• Qualsiasi progetto ha un sovraccarico, ovvero azioni richieste per raggiungere gli obiettivi, che pur non essendo direttamente l’obiettivo dovrebbero perciò restare minime. Per Ansel, è la manutenzione del sito web, della documentazione, dei server, dei pacchetti compilati nelle build notturne, la pulizia del codice, il debugging, i test di regressione, il supporto multipiattaforma, la gestione delle issue, ecc.
• Gli obiettivi e il sovraccarico dovrebbero essere espressi in termini di compiti da svolgere per risolvere problemi (issue). Se non c’è alcun problema da risolvere, allora non c’è alcun lavoro da fare: anche lo status quo va benissimo, non creare lavoro solo per il gusto di farlo.
• a causa della limitazione delle risorse, i compiti devono essere ordinati in base alla loro priorità.

Il documento seguente mira a definire questa priorità.

Ansel è nato come fork di Darktable perché Darktable non ha alcun obiettivo chiaro, alcuna gestione delle priorità, e il sovraccarico aumenta ogni anno, il che è il marchio di fabbrica delle fabbriche di burn-out ed è insostenibile nel medio termine.

Definire buone issue

La gestione dei progetti funziona meglio con compiti SMART. S.M.A.R.T. sta per:

• Specifico (es: trovare l’URI delle immagini che Ansel ha esportato sul filesystem e aprirle)
• Misurabile (es: numero di clic/passaggi richiesti, tempo di CPU per svolgere il compito su una certa piattaforma di destinazione)
• Attuabile/Realizzabile (es: può essere integrato nella base di codice attuale con solo riscritture minori, richiede solo poche centinaia di righe di codice)
• Pertinente/Ragionevole (es: fa parte di un flusso di lavoro fotografico abbastanza generale, verrebbe usato da una parte significativa degli utenti)
• Delimitato nel tempo (es: richiede al massimo 70 ore-uomo).

Una buona issue è quella che porta a un compito SMART. Per Ansel, questo significa issue focalizzate su un problema chiaramente definito che riguarda una fase chiaramente definita del flusso di lavoro di editing delle immagini («Ho problemi a fare X a causa di Y e vorrei Z»).

Le domande e le discussioni generali dovrebbero avvenire su https://community.ansel.photos.

Le cattive issue sono:

• troppo ampie (“automatizzare il flusso di lavoro”, “migliorare la UX”),
• focalizzate sul mezzo (“usare una rete neurale”, “estendere la curva dei toni”) invece che sull’obiettivo (“mascherare via il cielo”, “controllare selettivamente la saturazione”),
• fuori ambito (“portare su Android”, “passare a Qt”, “passare a Vulkan”)
• che riguardano librerie/progetti di terze parti (Rawspeed, Libraw, Exiv2, Lensfun, GPhoto2, Gtk, ecc.),
• troppo soggettive (“per favore fai le cose come quell’altro software che ho usato in passato e che mi piace davvero”). Ciò che piace all’utente A sarà detestato dall’utente B, non possiamo lavorare in questo modo.

Nota a margine: alcune issue possono sembrare cose che richiedono altro codice, mentre in realtà necessitano di una migliore documentazione delle funzioni attuali, o di leggeri ritocchi alla GUI (rinominare etichette, riorganizzare i widget), quindi è qualcosa da tenere a mente prima di partire in quarta.

Definire le priorità

In un mondo ideale, i compiti (ovvero le buone issue) verrebbero aggiunti alla lista delle cose da fare in modo lineare, man mano che si raggiungono i traguardi, e il prodotto del loro codice verrebbe testato per un paio di settimane mentre il codice è per il resto congelato, finché non si dimostra che tutto regge, nel qual caso scongeleremmo il codice e passeremmo al compito successivo nella lista delle cose da fare.

Il problema è che questo implica che tutti siano ai posti di combattimento per la fase di test, così da non congelare il codice troppo a lungo. Poiché ciò non accade (le persone vanno in vacanza, hanno figli, traslocano, cambiano lavoro, hanno una vita…), dobbiamo parallelizzare il test del prodotto dei compiti precedenti mentre lavoriamo su quello successivo, per essere efficienti.

Questo per dire che la lista delle cose da fare non è lineare e alcune cose importanti potrebbero essere aggiunte o rimosse dinamicamente, a seconda di cosa accade. Il problema è quindi determinare cosa costituisce qualcosa di abbastanza importante da sconvolgere la pianificazione.

Non esiste una regola definitiva qui, quindi dovrai usare il tuo miglior giudizio, ma ci sono alcune regole empiriche:

• qualcosa che si è rotto di recente (una regressione) è più facile da individuare e correggere prima piuttosto che dopo, quindi nel grande schema delle cose, potrebbe essere meno lavoro complessivo farlo prima,
• qualcosa che impedisce del tutto il funzionamento del software (crash, file di output corrotti, perdita di dati) è abbastanza critico da avere la precedenza sui miglioramenti e sulle correzioni più cosmetiche,
• qualcosa che impatta un gran numero di utenti e per cui non si può trovare alcuna soluzione alternativa avrà anch’esso la precedenza.

Al contrario, qualsiasi cosa impatti un piccolo numero di utenti, o funzioni di nicchia/secondarie, o piccole seccature che hanno soluzioni alternative, non è abbastanza critica da giustificare lo sconvolgimento della pianificazione. Queste verranno aggiunte alla coda con logica first-in/first-out.

Ansel ha 4 livelli di priorità, impostati come tag delle issue:

• priority: critical: Riguarda funzionalità basilari e fondamentali del software in un modo che ne impedisce del tutto il funzionamento,
• priority: high: Riguarda funzionalità basilari e fondamentali del software in un modo che ne degrada gravemente l’usabilità,
• priority: medium: Riguarda funzionalità basilari e fondamentali del software in un modo che ne degrada lievemente l’usabilità (soluzioni alternative disponibili),
• priority: low: Riguarda funzionalità opzionali e di nicchia

Definire i traguardi

I parametri dei moduli vengono salvati come blob binari. Li gestiamo trattando la loro dimensione in bit. Quando viene aggiunto un nuovo parametro, dobbiamo scrivere codice per gestire la conversione, ovvero la diversa dimensione in bit del blob del parametro, e incrementiamo la versione interna dei parametri dei moduli. Non viene scritto alcun codice per la retrocompatibilità, quindi le immagini modificate con moduli più recenti non possono essere aperte in moduli più vecchi. I parametri dei moduli sono usati anche negli stili, nei preset e nei file XMP.

Per queste ragioni, qualsiasi issue che porterebbe ad aggiungere parametri nei moduli (siano essi i moduli di elaborazione dell’immagine nella camera oscura, o i moduli del tavolo luminoso che gestiscono l’esportazione e i metadati), romperebbe la retrocompatibilità e deve essere pianificata per la successiva versione maggiore del software (1.0, 2.0, 3.0, ecc.). Questo significa che all’interno della stessa versione maggiore sono consentite solo modifiche alla GUI e al comportamento, e possono essere pianificate per la successiva versione minore (0.1, 0.2, 0.3, poi 1.1, 1.2, 1.3, ecc.).

Ansel ha sempre solo 2 traguardi: la successiva versione minore e la successiva versione maggiore.

Definire la difficoltà

La difficoltà è direttamente correlata alla quantità di lavoro richiesta da un compito, ovvero:

• il numero di righe di codice da scrivere,
• il numero di file da modificare,
• la probabilità di rompere funzioni esistenti, che comporta lavoro di test aggiuntivo,
• l’esistenza di funzioni simili o di teoria già scritta per realizzare il compito,
• il sovraccarico di far funzionare le modifiche e le funzioni in modo affidabile su diversi sistemi operativi.

Stimare la difficoltà in modo accurato è qualcosa che solo uno sviluppatore esperto può fare.

Definire la natura

La natura delle issue viene gestita con le etichette. Abbiamo:

• regressioni (roba che funzionava ma è stata rotta da modifiche relativamente recenti),
• bug (roba che non ha mai funzionato negli ultimi anni),
• miglioramenti (roba che deve essere migliorata o aggiunta),
• wontfix (non è un bug, ma una funzione o una scelta di progettazione o una necessità imposta da dipendenze di terze parti),
• question (non dovrebbe stare su Github, ma su https://community.ansel.photos),
• duplicate (issue già segnalata),
• unclear (l’issue non può essere compresa),
• invalid (l’issue è “cattiva” secondo la definizione di buona issue di cui sopra).

Le priorità sono relative

Vedi https://www.youtube.com/watch?v=8fnfeuoh4s8 . Dover riparare l’auto per cambiare la lampadina è un’ottima metafora del fare codice su un software di 12 anni con centinaia di migliaia di righe di codice scritte da persone che non si parlavano tra loro e non documentavano le proprie modifiche. Riparare l’auto non è la priorità assoluta finché non diventa il prerequisito per riparare la lampadina ad alta priorità.

Il tuo lavoro di gestore delle issue

In definitiva, solo uno sviluppatore esperto sarà in grado di gestire accuratamente le issue. Ma la ragione impone che uno sviluppatore esperto venga impiegato per fare cose che solo uno sviluppatore esperto può fare: scrivere codice semplice per risolvere in modo efficiente problemi tecnici che richiedono una certa quantità di teoria e di progettazione.

Il compromesso è avere dei gestori delle issue che aiutino a dare priorità alle issue ovvie, così che gli sviluppatori debbano occuparsi solo delle issue meno ovvie e concentrarsi sulla scrittura del codice.

1. etichetta solo le issue che comprendi e che ti senti a tuo agio a gestire. Non devi farle tutte, va bene se non lo sai.
2. per le issue che comprendi:
   • assegna un’etichetta di priorità se puoi,
   • assegna un’etichetta di natura se puoi,
   • assegna un traguardo se puoi,
   • chiudi immediatamente l’issue se è invalid o duplicate.
3. per le issue che non comprendi:
   • prova a fare più domande all’autore,
   • assicurati che gli autori compilino tutte le informazioni pertinenti (OS, hardware, passaggi per riprodurre i bug),
4. è meglio se non fai nulla piuttosto che farlo male: le issue senza etichette sono più facili da individuare rispetto alle issue con etichette sbagliate.
5. non esitare a indire riunioni video: meglio sedersi insieme per 30 min per fare una chiacchierata produttiva e aggiustare le decisioni piuttosto che scambiarsi infiniti thread di messaggi inutili.

Grazie !