Udvikler vs kunde toneforudsætninger for de samme commits

Hvorfor separate tone-presets?

Jeg startede dette projekt, fordi jeg så, at teams spildte tid på at omskrive den samme changelog-indtastning til to forskellige læsere. Ingeniører har brug for at se, hvad der er ændret i koden, hvilke filer der er berørt, og hvilke interne APIs der er brudt. Produktchefer, supportpersonale og slutbrugere er interesseret i, hvad ændringen betyder for dem: nye funktioner, rettede fejl, forbedret ydeevne eller fjernede begrænsninger. En enkelt tone kan ikke betjene begge grupper godt. Ved at oprette to forskellige presets, der opererer på den samme commitliste, holder vi sandhedskilden uændret, mens vi leverer tilpassede meddelelser. Denne tilgang låter også SemVer-mærkningen forblive den eneste kilde til kontraktmæssig betydning, fordi mærkningen er knyttet til commit-gruppen, ikke til formuleringen.

Udvikler tone forudindstillet: detaljer først

Commit-niveau detaljer

Når udviklerforudindstillingen er aktiv, udvider AI hver commit til en sætning, der inkluderer filstien, den modificerede funktion eller klasse og naturen af ændringen (tilføjelse, sletning, omstrukturering). For eksempel bliver en commit, der fikserer en null-peger i src/api/user.go: „Fixed nil pointer dereference i GetUserByID, når den indgående ID er nul, tilføjet vagtklausul og enhedstest.“

Link til sporingssystemer

Hvis commit-beskedeen indeholder et problem-ID (f.eks. ABC-123), omgiver forudindstillingen det med en link til sporet, under forudsætning af, at teamet har konfigureret basis-URL'en. Dette giver ingeniørerne mulighed for at gå direkte til diskussionen eller design-dokumentet uden at forlade ændringsloggen.

Inklusion af teknisk kontekst

Forudindstillingen tilføjer eventuelle relevante compiler-advarsler, ændringer i testdækning eller ydeevne-benchmark-deltaer, der optrådte i CI-kørslen associeret med commit. Dette giver en hurtig sundhedstjek for den modificerede område.

Sikkerheds- og compliancekontrol for LLM-udgang

Fordi teksten er genereret af et sprogmodel, kører jeg det gennem en letvægts-sikkerhedsfilter, der checker for ikke-tilladt indhold. Filteret refererer til OWASP LLM Top 10 for prompt-injektionsrisici og NIST AI Risk Management Framework for vejledning i at håndtere hallucinationer og bias. Hvis et segment udløser en regel, bliver det markeret til menneskelig gennemgang før offentliggørelse.

Eksempel på liste for en typisk udgivelse

- Tilføjet RetryPolicy-grænseflade i src/retry/policy.go for at tillade udskiftelige tilbageholdelsesstrategier. - Fjernet forældet LegacyCache-struct fra src/cache/legacy.go; alle kald migreret til LRUCache. - Fixet racemodning i WorkerPool.Start, hvor en nil-kanal kunne lukkes to gange; tilføjet mutex-vagt. - Opdateret Go-modul github.com/stretchr/testify fra v1.7.0 til v1.8.2 for at hente sikkerhedsretning for assert-pakke. - Tilføjet benchmarks for JSONEncoder, der viser 12% reduktion i allokeringsstørrelse for payload under 10KB.

Kundetone forudindstillet: fordel-først

Resultatfokuseret sprog

Med kundeforudindstillingen omskriver AI hver commit til en sætning, der beskriver, hvad brugeren nu kan gøre, eller hvilket problem der er løst. Teknisk jargon erstattes med almindelige termer. Den samme null-peger-retning bliver: "Brugere vil ikke længere se en fejl, når de indtaster en værdi på nul i brugeropslagsfeltet."

Undgåelse af interne identifikatorer

Commit-hashes, grennavne og interne problemsnumre udelades, medmindre de er en del af en offentlig funktion eller en versioneret API-endpoint, som kunderne måske henviser til. Målet er at holde støjen lav.

Fremhævelse af brugerens påvirkning

Hvis en commit forbedrer ydeevnen, oversætter forudindstillingen benchmark-gevinsten til en brugervisuel erklæring: "Sideskifttider er nu op til 15% hurtigere på mobile enheder." Hvis en commit fjerner en begrænsning, lyder den: "Du kan nu uploade filer op til 100 MB i stedet for den tidligere 25 MB-grænse."

Link til offentlig dokumentation

Når en ændring berører en offentlig API-endpoint eller en konfigurationsindstilling, tilføjer forudindstillingen et link til den relevante dokumentationssektion, under forudsætning af, at dokumentsitet følger en forudsigelig URL-mønster (f.eks. https://docs.example.com/api/v2/brugere).

Eksempeledliste for samme udgivelse

- Genprøve-logik tilpasser sig nu midlertidige netværksfejl, hvilket reducerer mislykkede uploads på ustabile forbindelser. - Den gamle cacheimplementering er fjernet; den nye cache bruger mindre hukommelse og rydder gamle poster automatisk. - En sjælden fejl, der kunne opstå, når mange arbejdere startede samtidig, er blevet rettet. - En tredjepartsbibliotek er opdateret for at løse en sikkerhedsmeddelelse; ingen handling er nødvendig fra dig. - JSON-svar er nu lettere, hvilket reducerer dataforbruget på målede forbindelser.

Fra commit-diff til to narrativer

Parsing og gruppering

Rørledningen begynder med at køre git log --pretty=format:%H %s %b --since="1 uge siden" for at samle commits siden den sidste tag. Hver commit parses for sin konventionelle commit-type (feat, fix, perf, refactor osv.) og omfang. Commits med samme type og SemVer implikation grupperes sammen, da de vil dele samme versionshop

Anvendelse af tone-specifikke prompts

For hver gruppe opbygger jeg to prompts: en tilpasset til udviklerpræsæt, en til kundepræsæt. Udviklerprompten beder om "en detaljeret, teknisk beskrivelse, der inkluderer filnavne, symboler og eventuelle relevante test- eller benchmarkændringer." Kundeprompten beder om "en koncis, fordelingsorienteret forklaring, der undgår internt jargon og fokuserer på, hvad brugeren oplever." Den samme liste af commits føder begge prompts, så de underliggende kendsgerninger forbliver identiske

Menneske-i-løkken gennemgang

AI-udgangen lander i en udraftseditor, hvor en vedligeholder kan acceptere, redigere eller afvise hver sætning. Jeg har fundet, at de fleste redigeringer er mindre ordvalgsjusteringer snarere end faktuelle ændringer, hvilket viser, at modellen er god til at blive sand til kilde-diff'en. Efter gennemgang renderes udraften til Markdown og derefter HTML til publicering

Tabel: mapping af konventionelle commit-typer til tone-frasering

Commit-type | Udvikler-frasering eksempel | Kunde-frasering eksempel feat | Tilføjet ExportCSV-metode til ReportService, der streamer rækker for at reducere hukommelsesbrug. | Du kan nu downloade rapporter som CSV-filer direkte fra eksportknappen. fix | Løst deadlock i JobQueue.Push, når en nil-job blev kørt under høj belastning. | Job vil ikke længere blive fast, når systemet er beskæftiget. perf | Erstattet O(n²)-søgning i TagIndex.Find med en hash-kort, der reducerer ventetid fra 12 ms til 0,8 ms for 10.000 tags. | Tagsøgninger er nu mærkbart hurtigere, især med store biblioteker. refactor | Uddraget PasswordValidator-grænseflade fra AuthHandler for at tillade justerbare styrke-regler. | Adgangskravsregler kan nu justeres uden at ændre kerne-login-kode. docs | Opdateret API.md med ny PATCH /users/:id-endpoint-beskrivelse og eksempel-payload. | Hjælpesenteret viser nu, hvordan du kan opdatere en brugerprofil delvist.

Bevaring af SemVer-betydning på tværs af toner

Regler for versionshop kun fastgøres til commits

SemVer-mærket bestemmes udelukkende af de konventionelle commit-typer i gruppen: en feat udløser en mindre hop, en fix en patch, og en brudende ændring en større hop. Da tone-forudindstillingerne ikke ændrer commit-beskedene eller deres typer, er den resulterende versionsnummer identisk, uanset om du læser udvikler- eller kundeversionen.

Kontrakt-konsistens

Jeg behandler SemVer-mærket som kontrakten mellem producenten og forbrugeren af softwaren. Ændringsloggen er blot en menneske-læselig udtryk for denne kontrakt. Ved at holde kontrakten urørt, kan teams afhænge af automatiserede værktøjer (som release-robotter eller afhængigheds-tjekkeren) til at fortolke versionen korrekt, mens den dobbelte tone-ændringslog betjener de to målgrupper uden at skabe tvetydighed.

Eksempel på en major udgivelse

Antag, at et commit tilføjer BREAKING CHANGE: fjern legacy v1 API. Udvikler-forudindstillingen vil notere de præcise fil-sletninger og migrations-trinnene, der kræves. Kunde-forudindstillingen vil forklare, at den gamle API-endpoint ikke længere er tilgængelig og pege brugere til v2-dokumentationen. I begge tilfælde flyttes versionen fra 2.4.1 til 3.0.0, hvilket bevarer den kontrakt-mæssige betydning.

Hvad dette ikke er

Jeg vil gerne gøre det klart, hvad denne tilgang ikke kan, så du kan sætte realistiske forventninger.

- Den garanterer ikke, at hver eneste genereret sætning vil være perfekt tone-mæssigt; lejlighedsvis kan over-teknisk formuleringsændring glide ind i kundeuftekten, eller vag fordelssprog kan optræde i udvikleruftekten. Menneskelig gennemgang er stadig nødvendig. - Den er ikke en 100 % erstatning for en dedikeret teknisk forfatter eller en produktmarkedsfører. AI'en accelererer den første gennemgang, men nuancer, brandstemme og juridiske disclaimer stadig kræver en persons berøring. - Den eliminerer ikke behovet for klar commit-hygiejne. Hvis commit-besked er vage eller mangler konventionel commit-struktur, vil grupperne være mindre nøjagtige og outputtet vil være mindre nyttigt. - Den er ikke et magisk værktøj, der automatisk tilfredsstiller hver eneste regulator eller tilgængelighedsretningslinje. Sikkerhedstjek, som jeg har tilføjet, er grundlæggende; du bør stadig køre din egen overholdelsesgennemgang. - Den lover ikke, at ændringsloggen aldrig vil gå glip af en ændring. Hvis en commit er udeladt fra git-log-området (f.eks. på grund af en lav klone eller en fejlfilter), vil den ikke optræde i nogen af de to toner.

Referencer

- OWASP LLM Top 10 - NIST AI Risk Management Framework

Relaterede læsninger

- Grupperede ændringslog fra commits (ikke rå git log) — Changelog AI - Den LX AI Micro-SaaS Emne Matrix