Tono dello sviluppatore vs tono del cliente per gli stessi commit

Perché separare i preset di tono?

Ho iniziato questo progetto perché ho visto che i team sprecavano tempo riscrivendo la stessa voce del registro dei cambiamenti per due lettori diversi. Gli ingegneri devono vedere cosa è cambiato nel codice, quali file sono stati modificati e quali API interne sono state modificate. I responsabili del prodotto, lo staff di supporto e gli utenti finali si interessano a cosa significa il cambiamento per loro: nuove funzionalità, bug risolti, prestazioni migliorate o limiti rimossi. Un unico tono non può servire bene entrambi i gruppi. Creando due preset distinti che operano sulla stessa lista di commit, manteniamo invariata la fonte di verità mentre consegniamo messaggi personalizzati. Questo approccio consente anche di mantenere l'etichetta SemVer come unica fonte di significato contrattuale, poiché l'etichetta è attaccata al gruppo di commit, non alla formulazione.

Impostazione del tono dello sviluppatore: dettagli prima di tutto

Dettagli a livello di commit

Quando l'impostazione dello sviluppatore è attiva, l'AI espande ogni commit in una frase che include il percorso del file, la funzione o la classe modificata e la natura del cambiamento (aggiunta, eliminazione, refactoring). Ad esempio, un commit che risolve un problema di null-pointer in src/api/user.go diventa: "Risolti riferimenti null in GetUserByID quando l'ID in ingresso è zero, aggiunta di una clausola di guardia e di un test unitario."

Collegamento ai sistemi di tracciamento

Se il messaggio di commit contiene un ID di problema (ad esempio ABC-123), l'impostazione lo avvolge in un collegamento al tracker, assumendo che il team abbia configurato l'URL di base. Ciò consente agli ingegneri di passare direttamente alla discussione o al documento di progettazione senza lasciare il registro delle modifiche.

Inclusione del contesto tecnico

L'impostazione aggiunge eventuali avvertimenti del compilatore, modifiche della copertura dei test o modifiche delle prestazioni dei benchmark che sono apparsi nell'esecuzione del CI associata al commit. Ciò fornisce un rapido controllo di salute per l'area modificata.

Controlli di sicurezza e conformità per l'output LLM

Poiché il testo è generato da un modello linguistico, lo eseguo attraverso un filtro di sicurezza leggero che controlla il contenuto non consentito. Il filtro fa riferimento all'OWASP LLM Top 10 per i rischi di iniezione di prompt e al quadro di gestione dei rischi AI del NIST per la gestione delle allucinazioni e dei pregiudizi. Se un segmento attiva una regola, viene contrassegnato per la revisione umana prima della pubblicazione.

Esempio di elenco per una versione tipica

- Aggiunta dell'interfaccia RetryPolicy in src/retry/policy.go per consentire strategie di back-off plug-in. - Rimozione della struttura LegacyCache deprecata da src/cache/legacy.go; tutti i chiamanti migrati a LRUCache. - Risolto il problema di condizione di gara in WorkerPool.Start dove un canale nil poteva essere chiuso due volte; aggiunta di una guardia mutex. - Aggiornamento del modulo Go github.com/stretchr/testify da v1.7.0 a v1.8.2 per applicare la patch di sicurezza per il pacchetto assert. - Aggiunta di benchmark per JSONEncoder che mostrano una riduzione del 12% della dimensione dell'allocazione per payload inferiori a 10KB.

Impostazione del tono del cliente: benefit-first

Linguaggio focalizzato sul risultato

Con l'impostazione del cliente, l'AI riscrive ogni commit in una frase che descrive cosa l'utente può fare ora o quale problema è stato risolto. I termini tecnici vengono sostituiti con termini semplici. La stessa correzione del puntatore nullo diventa: "Gli utenti non vedranno più un errore quando immettono un ID con valore zero nel campo di ricerca dell'utente."

Evitare identificatori interni

Le hash dei commit, i nomi delle branch e i numeri interni dei problemi vengono omessi a meno che non facciano parte di una funzionalità pubblica o di un endpoint API versionato che i clienti potrebbero fare riferimento. L'obiettivo è mantenere il rumore basso.

Evidenziare l'impatto sull'utente

Se un commit migliora le prestazioni, l'impostazione traduce il guadagno del benchmark in una dichiarazione visibile all'utente: "I tempi di caricamento della pagina sono ora fino al 15% più veloci sui dispositivi mobili." Se un commit rimuove un limite, si legge: "Ora puoi caricare file fino a 100 MB invece del limite precedente di 25 MB."

Collegamento alla documentazione pubblica

Quando un cambiamento tocca un endpoint API pubblico o un'opzione di configurazione, l'impostazione aggiunge un collegamento alla sezione di documentazione pertinente, assumendo che il sito della documentazione segua uno schema di URL prevedibile (ad esempio, https://docs.example.com/api/v2/utenti).

Esempio di elenco per lo stesso rilascio

- La logica di ritentativo si adatta ora ai glitch di rete temporanei, riducendo i caricamenti non riusciti su connessioni instabili. - L'implementazione della cache vecchia è stata rimossa; la nuova cache utilizza meno memoria e cancella automaticamente le voci obsolete. - È stato risolto un crash raro che poteva verificarsi quando molti lavoratori partivano contemporaneamente. - La libreria di terze parti è stata aggiornata per affrontare un avviso di sicurezza; non è necessaria alcuna azione da parte tua. - Le risposte JSON sono ora più leggere, il che riduce l'utilizzo dei dati sulle connessioni a pagamento.

Da diff di commit a due narrative

Parsing e raggruppamento

La pipeline inizia eseguendo git log --pretty=format:%H %s %b --since="1 settimana fa" per raccogliere i commit dall'ultimo tag. Ogni commit viene parsato per il suo tipo di commit convenzionale (feat, fix, perf, refactor, ecc.) e ambito. I commit con lo stesso tipo e implicazione SemVer vengono raggruppati insieme perché condivideranno lo stesso incremento di versione.

Applicazione di prompt specifici per il tono

Per ogni gruppo creo due prompt: uno regolato per l'impostazione dello sviluppatore, uno per l'impostazione del cliente. Il prompt dello sviluppatore chiede una "descrizione dettagliata e tecnica che include nomi di file, simboli e eventuali modifiche ai test o benchmark rilevanti". Il prompt del cliente chiede una "spiegazione concisa e orientata ai benefici che evita il gergo interno e si concentra su ciò che l'utente sperimenta". La stessa lista di commit alimenta entrambi i prompt, assicurando che i fatti sottostanti rimangano identici.

Revisione con intervento umano

L'output dell'AI atterra in un editor di bozza dove un manutentore può accettare, modificare o rifiutare ogni frase. Ho trovato che la maggior parte delle modifiche sono piccole correzioni di parole piuttosto che modifiche fattuali, il che mostra che il modello è bravo a rimanere fedele alla diff di origine. Dopo la revisione, la bozza viene renderizzata in Markdown e quindi in HTML per la pubblicazione.

Tabella: mappatura dei tipi di commit convenzionali alla fraseologia del tono

Tipo di commit | Esempio di fraseologia per lo sviluppatore | Esempio di fraseologia per il cliente feat | Aggiunto il metodo ExportCSV a ReportService che streaming le righe per ridurre l'utilizzo della memoria. | Ora puoi scaricare i report come file CSV direttamente dal pulsante di esportazione. fix | Risolto il deadlock in JobQueue.Push quando un lavoro nil era in coda sotto carico elevato. | I lavori non si bloccheranno più quando il sistema è occupato. perf | Sostituito il lookup O(n²) in TagIndex.Find con una mappa hash, riducendo la latenza da 12 ms a 0,8 ms per 10 k tag. | Le ricerche di tag sono ora notevolmente più veloci, soprattutto con librerie grandi. refactor | Estratto l'interfaccia PasswordValidator da AuthHandler per consentire regole di forza pluggabili. | I requisiti di password possono ora essere regolati senza modificare il codice di accesso principale. docs | Aggiornato API.md con la nuova descrizione dell'endpoint PATCH /users/:id e payload di esempio. | Il centro di aiuto ora mostra come aggiornare parzialmente un profilo utente.

Conservazione del significato di SemVer attraverso toni

Le regole di incremento della versione rimangono ancorate ai commit

L'etichetta SemVer è determinata esclusivamente dai tipi di commit convenzionali nel gruppo: un feat attiva un incremento minore, un fix un incremento di patch e un cambiamento di rottura un incremento maggiore. Poiché i preset di tono non alterano i messaggi di commit o i loro tipi, il numero di versione risultante è identico sia che si legga la versione per sviluppatori che quella per clienti.

Coerenza del contratto

Tratto l'etichetta SemVer come il contratto tra il produttore e il consumatore del software. Il registro delle modifiche è semplicemente un'espressione leggibile dall'uomo di quel contratto. Mantenendo il contratto intatto, i team possono affidarsi a strumenti automatizzati (come bot di rilascio o controllori di dipendenze) per interpretare correttamente la versione, mentre il registro delle modifiche a doppio tono serve i due pubblici senza creare ambiguità.

Esempio di una versione principale

Supponiamo che un commit aggiunga BREAKING CHANGE: rimuovi API legacy v1. Il preset per sviluppatori noterà le esatte eliminazioni di file e i passaggi di migrazione richiesti. Il preset per clienti spiegherà che il vecchio endpoint API non è più disponibile e indirizzerà gli utenti alla documentazione v2. In entrambi i casi, la versione passerà da 2.4.1 a 3.0.0, conservando il significato contrattuale.

Cosa non è

Voglio essere chiaro sui limiti di questo approccio in modo che tu possa avere aspettative realistiche.

- Non garantisce che ogni frase generata sarà perfetta dal punto di vista del tono; occasionalmente, una frase troppo tecnica potrebbe essere inserita nel draft del cliente o un linguaggio di beneficio vago potrebbe apparire nel draft dello sviluppatore. È ancora necessaria una revisione umana. - Non è un sostituto al 100% di uno scrittore tecnico dedicato o di un marketer di prodotto. L'AI velocizza il primo passaggio, ma la sfumatura, la voce del marchio e le dichiarazioni legali richiedono ancora il tocco di una persona. - Non elimina la necessità di una chiara igiene dei commit. Se i messaggi di commit sono vaghi o mancano della struttura dei commit convenzionali, i gruppi saranno meno precisi e l'output sarà meno utile. - Non è uno strumento magico che soddisferà automaticamente ogni regolatore o linea guida sull'accessibilità. I controlli di sicurezza che ho aggiunto sono di base; dovresti comunque eseguire la tua propia revisione di conformità. - Non promette che il registro delle modifiche non perderà mai una modifica. Se un commit viene omesso dal git log range (ad esempio, a causa di un clone superficiale o di un filtro errato), non apparirà in nessuno dei toni.

Riferimenti

- OWASP LLM Top 10 - NIST AI Risk Management Framework

- Changelog AI, EU AI Act, GDPR

Letture correlate

- Changelog raggruppati da commit (non raw git log) — Changelog AI - La matrice di argomenti LX AI Micro-SaaS