Template di richiesta funzionalità che diventa changelog

Un template di richiesta funzionalità è un modulo con quattro domande: cosa sta cercando di fare la persona, cosa glielo impedisce, cosa ha provato invece, e come vuole essere avvisata quando è fatto. Tutto il resto che di solito appare su uno, selettori di priorità, stime di sforzo, punteggi di valore business, è per il team che riceve la richiesta, e viene compilato male da chi la invia.

Le richieste ordinate sono il test sbagliato per un template. Quello giusto: sei mesi dopo, quando la funzionalità viene rilasciata, qualcuno può trovare la richiesta, capirla, e avvisare chi l’ha scritta? La maggior parte dei template sono progettati per l’ammissione. Questo è progettato per il giorno in cui si chiude il ciclo.

Cosa dovrebbe includere un template di richiesta funzionalità?

Dovrebbe includere l’obiettivo, il blocco, la soluzione alternativa, e un modo per tornare a chi ha chiesto. Quattro campi, in quest’ordine, ciascuno risponde a una domanda che il team farà dopo.

Ciò che manca deliberatamente: una soluzione proposta come campo obbligatorio (benvenuta come commento, sbagliata come inquadratura), un selettore di priorità (chiunque invii sceglie alta), e qualsiasi stima di sforzo o valore (compito del team, dopo lo smistamento). Un template che chiede una soluzione riceve richieste di pulsanti; un template che chiede un obiettivo riceve richieste di risultati, e su risultati si scrive una voce di changelog.

Il template

Questo è il template di issue GitHub che usiamo, come modulo. Incollatelo in .github/ISSUE_TEMPLATE/feature_request.yml e viene reso come modulo strutturato nella pagina nuovo issue. Le richieste archiviate attraverso di esso diventano issue con gli stessi campi di quelle archiviate da un widget di feedback, il che conta per la sezione successiva.

name: Feature request
description: What you are trying to do, and what stops you.
labels: ["feature-request"]
body:
  - type: textarea
    id: goal
    attributes:
      label: What are you trying to do?
      description: >-
        The outcome, not the button. "Export a month of invoices as one
        PDF" beats "add a PDF export".
    validations:
      required: true
  - type: textarea
    id: blocker
    attributes:
      label: What stops you today?
      description: >-
        Where the product runs out. An error, a missing option, a limit.
    validations:
      required: true
  - type: textarea
    id: workaround
    attributes:
      label: What do you do instead?
      description: >-
        The spreadsheet, the script, the manual step. "Nothing, I gave
        up" is a valid answer.
  - type: input
    id: contact
    attributes:
      label: How should we tell you when it ships?
      description: >-
        An email address, or leave blank to be notified only on this
        issue.

Due dettagli fanno il lavoro. labels: ["feature-request"] significa che la richiesta viene classificata alla creazione, invece di aspettare che qualcuno la smisti. E l’ultimo campo esiste perché “ti faremo sapere” è una promessa, e una promessa ha bisogno di un indirizzo.

Quali etichette dovrebbe portare una richiesta di funzionalità?

Una richiesta di funzionalità dovrebbe portare un’etichetta per cosa è, una per quanto è urgente, e una per da dove è arrivata. Tre etichette, tre assi, e ciascuno viene letto da una lettrice diversa.

Il widget applica i primi due assi e from-widget quando archivia un invio come issue; from-form e from-support sono suggerimenti per le richieste che arrivano per altre vie. Le etichette del widget sono un tipo (bug o feature-request, deciso da un classificatore solo dal messaggio), una priorità (una segnalazione di crash calma e concreta è alta; un duplicato di qualcosa già chiesto è bassa; qualsiasi cosa che anche solo accenni a un problema di sicurezza è bug e alta, qualunque sia la formulazione), e from-widget. Gli stessi tre assi funzionano per richieste che arrivano a mano attraverso il template sopra, ed è questo il punto: una richiesta è una richiesta, indipendentemente da dove sia entrata.

Un’altra convenzione: il widget rimuove l’indirizzo email di chi invia dal corpo dell’issue prima di archiviarlo, perché l’issue vive in un repository che può essere pubblico, e lo sostituisce con un riferimento di invio. L’indirizzo resta fuori dall’issue; chi ha inviato segue l’esito nel widget stesso. Fate lo stesso col campo di contatto se il vostro tracker è visibile a persone fuori dal team.

Come diventa una richiesta di funzionalità una voce di changelog?

Una richiesta di funzionalità diventa una voce di changelog quando una pull request chiude l’issue e la voce redatta da quella pull request collega indietro. Il meccanismo sono le parole chiave di chiusura di GitHub stessa: una PR la cui descrizione dice Fixes #142 chiude l’issue 142 al merge. Se le vostre voci di changelog sono redatte da pull request mergiate, la bozza può portare con sé il numero dell’issue, e la voce sa chi ha chiesto.

Questa è la ragione per cui il template chiede l’obiettivo piuttosto che la soluzione. Quando si scrive la voce, l’obiettivo è la frase di cui ha bisogno chi scrive: “Ora puoi esportare un mese di fatture come un unico PDF” è una voce di changelog. “Aggiunto export PDF” è un messaggio di commit. Gli strumenti per il changelog che redigono da pull request possono fare la raccolta e il collegamento; la formulazione ha ancora bisogno di una persona, e la persona ha bisogno dell’obiettivo.

Cosa succede quando viene rilasciato?

A chi ha chiesto viene detto, con link alla voce. Nel nostro setup questo è automatico per le richieste arrivate tramite il widget: un commento che dice “Shipped — ” con link alla voce pubblicata, pubblicato sull’issue non appena una persona approva la voce, mentre il widget mostra a chi ha inviato la stessa voce. Un issue aperto a mano da questo template non riceve alcun commento automatico; quel ciclo chiudetelo voi, con la stessa regola. Il commento viene pubblicato deliberatamente all’approvazione, non al merge: un commento che dice che qualcosa è live prima che lo sia è una promessa rotta con timestamp. Ogni richiesta viene notificata al massimo una volta; una seconda approvazione della stessa voce non produce un secondo commento.

Se lo fate a mano, vale la stessa regola. Non chiudete il ciclo dalla pull request. Chiudetelo dalla voce pubblicata, e chiudetelo una volta. Feed e widget portano la stessa voce a tutti quelli che non hanno chiesto, che sono la maggior parte; il commento è per chi ha chiesto.

Perché falliscono la maggior parte dei template di richiesta funzionalità

Sono progettati per rendere più facile lo smistamento e ci riescono, a costo dell’unico momento che conta per chi ha chiesto. Un template con dodici campi riceve meno richieste, e quelle che riceve vengono da persone con la pazienza di compilare dodici campi, che non è la stessa popolazione di chi ha bisogno della funzionalità. Un template con quattro campi, uno dei quali è “come ti contattiamo”, riceve più richieste e può onorarle tutte.

FAQ

Un template di richiesta funzionalità dovrebbe chiedere la priorità? No. Chiedete invece la soluzione alternativa. “Esporto in un foglio di calcolo e lo ridigito ogni venerdì” dice più sulla priorità di un menu a tendina che chi invia ha messo su alta.

Chi chiede dovrebbe proporre una soluzione? Può, nel testo libero. Non fatene l’inquadratura. Le richieste scritte come soluzioni sono più difficili da fondere tra loro e più difficili da trasformare in una voce di changelog.

Le richieste di funzionalità dovrebbero apparire su una roadmap pubblica? Una volta pianificate, sì: un’etichetta sullo stesso issue la mette nella colonna pianificata, e chi ha chiesto può vedere come si muove. L’articolo roadmap pubblica è il meccanismo.

Come gestisco i duplicati? Collegate la nuova richiesta all’issue esistente ed etichettatela priorità bassa; non chiudetela. Ogni duplicato è una persona in più da avvisare quando viene rilasciato. Con il commento automatico di Changeloop, quella persona viene avvisata solo se la pull request nomina anche il suo issue (Fixes #142, fixes #187).

Dove dovrebbe vivere il template? Nel repository che riceverà la pull request, così che funzioni la parola chiave di chiusura. Una richiesta in un tracker separato deve essere collegata a mano al merge, ed è quel passo a essere saltato.

Le affermazioni tecniche di questo articolo non sono state verificate in modo indipendente. Se qualcosa non è corretto, faccelo sapere e lo correggeremo.

Correlati su changeloop: Documentazione per sviluppatori, Strumenti di changelog a confronto