Ontw vs klant tooninstellingen voor dezelfde commits

Waarom aparte tooninstellingen?

Ik ben dit project begonnen omdat ik zag dat teams tijd verspilden met het opnieuw schrijven van dezelfde changelog-invoer voor twee verschillende lezers. Ingenieurs moeten zien wat er in de code is veranderd, welke bestanden zijn aangeraakt en eventuele brekende interne API's. Productmanagers, ondersteunend personeel en eindgebruikers zijn geïnteresseerd in wat de verandering voor hen betekent: nieuwe functies, opgeloste bugs, verbeterde prestaties of verwijderde limieten. Een enkele toon kan beide groepen niet goed bedienen. Door twee verschillende instellingen te maken die werken op dezelfde lijst met commits, houden we de bron van de waarheid ongewijzigd en leveren we aangepaste berichten. Deze aanpak laat ook de SemVer-label de enige bron van contractuele betekenis blijven, omdat het label is gekoppeld aan de commit-groep, niet aan de bewoording.

Ontwikkelaarstoontje: detail-eerst

Commitniveau-detail

Wanneer het ontwikkelaarstoontje actief is, breidt de AI elke commit uit tot een zin die het bestandspad, de gewijzigde functie of klasse en de aard van de wijziging (toevoeging, verwijdering, refactor) bevat. Bijvoorbeeld, een commit die een null-pointer in src/api/user.go repareert, wordt: "Fixed nil pointer dereference in GetUserByID wanneer de inkomende ID nul is, voegde guardclausule en eenheids-test toe"

Koppeling naar tracksysteem

Als het commitbericht een issue-ID bevat (bijv. ABC-123), omvat het toontje deze in een koppeling naar de tracker, onder de voorwaarde dat het team de basis-URL heeft geconfigureerd. Dit laat engineers toe om rechtstreeks naar de discussie of ontwerpdocument te springen zonder de changelog te verlaten

Opnemen van technische context

Het toontje voegt eventuele relevante compilerwaarschuwingen, wijzigingen in testdekking of prestatiebenchmarks toe die zijn verschenen in de CI-run die is gekoppeld aan de commit. Dit geeft een snelle gezondheidscheck voor het gewijzigde gebied

Veiligheids- en compliancecontroles voor LLM-uitvoer

Omdat de tekst is gegenereerd door een taalmodel, voer ik deze door een lichtgewicht veiligheidsfilter dat controleert op niet-toegestane inhoud. Het filter verwijst naar de OWASP LLM Top 10 voor prompt-injectierisico's en het NIST AI Risk Management Framework voor richtlijnen over het beheersen van hallucinaties en vooroordelen. Als een segment een regel activeert, wordt het gemarkeerd voor menselijke controle voordat het wordt gepubliceerd

Voorbeeldlijst voor een typische release

- Toegevoegd RetryPolicy-interface in src/retry/policy.go om plug-in-achteruitgangsstrategieën toe te staan. - Verwijderde verouderde LegacyCache-struct uit src/cache/legacy.go; alle callers gemigreerd naar LRUCache. - Gefixt raceconditie in WorkerPool.Start waar een nil-kanaal tweemaal kon worden gesloten; voegde mutex-beveiliging toe. - Bijgewerkt Go-module github.com/stretchr/testify van v1.7.0 naar v1.8.2 om beveiligingspatch voor assert-pakket op te halen. - Toegevoegd benchmarks voor JSONEncoder die een reductie van 12% in toewijzingsgrootte voor payloads onder 10KB laten zien

Klanttoon voorinstelling: voordeel-eerst

Resultaatgerichte taal

Met de klantvoorinstelling herschrijft de AI elke commit naar een zin die beschrijft wat de gebruiker nu kan doen of welk probleem is opgelost. Technisch jargon wordt vervangen door eenvoudige termen. Dezelfde null-pointerfix wordt: "Gebruikers zullen geen fout meer zien wanneer ze een nulwaarde-ID intoetsen in het gebruikerszoekveld."

Interne identificatoren vermijden

Commit-hashes, branchnamen en interne issue-nummers worden weggelaten, tenzij ze deel uitmaken van een openbare functie-vlag of een versie-API-eindpunt dat klanten mogelijk verwijzen. Het doel is om de ruis laag te houden.

Gebruikersimpact benadrukken

Als een commit de prestaties verbetert, vertaalt de voorinstelling de benchmark-winst naar een gebruikerszichtbare verklaring: "Paginabelastingstijden zijn nu tot 15% sneller op mobiele apparaten." Als een commit een limiet verwijdert, wordt het: "U kunt nu bestanden uploaden tot 100 MB in plaats van de vorige limiet van 25 MB."

Koppeling naar openbare documentatie

Wanneer een wijziging een openbaar API-eindpunt of een configuratie-optie raakt, voegt de voorinstelling een koppeling toe naar de relevante documentatie-sectie, onder de voorwaarde dat de documentatie-site een voorspelbaar URL-patroon volgt (bijv. https://docs.example.com/api/v2/users).

Voorbeeldlijst voor dezelfde release

- De retry-logica past zich nu aan aan tijdelijke netwerkglitches, waardoor mislukte uploads op onbetrouwbare verbindingen worden verminderd. - De oude cache-implementatie is verwijderd; de nieuwe cache gebruikt minder geheugen en wischt verouderde items automatisch. - Een zeldzame crash is opgelost die kon optreden wanneer veel werknemers tegelijkertijd startten. - De derdepartijbibliotheek is bijgewerkt om een beveiligingsmelding aan te pakken; geen actie nodig van u. - JSON-antwoorden zijn nu lichter, waardoor de gegevensverbruik op gemeten verbindingen wordt verlaagd.

Van commit-diff naar twee verhalen

Parseren en groeperen

De pipeline begint met het uitvoeren van git log --pretty=format:%H %s %b --since="1 week ago" om commits te verzamelen sinds de laatste tag. Elke commit wordt geparsed voor zijn conventionele commit-type (feat, fix, perf, refactor, etc.) en scope. Commits met hetzelfde type en SemVer-implicatie worden gegroepeerd omdat ze dezelfde versie-uitbreiding zullen delen.

Toepassen van toon-specifieke prompts

Voor elke groep bouw ik twee prompts: een afgestemd op de ontwikkelaar-preset, een voor de klant-preset. De ontwikkelaar-prompt vraagt om "een gedetailleerde, technische beschrijving die bestandsnamen, symbolen en eventuele relevante test- of benchmark-wijzigingen bevat". De klant-prompt vraagt om "een bondige, voordeel-georiënteerde verklaring die interne jargon vermijdt en zich richt op wat de gebruiker ervaart". Dezelfde lijst met commits voedt beide prompts, waardoor de onderliggende feiten identiek blijven.

Mens-in-de-lus-beoordeling

De AI-uitvoer belandt in een concept-editor waar een beheerder elke zin kan accepteren, bewerken of afwijzen. Ik heb ontdekt dat de meeste bewerkingen kleine woordwijzigingen zijn in plaats van feitelijke wijzigingen, wat aantoont dat het model goed is in het trouw blijven aan de bron-diff. Na beoordeling wordt het concept omgezet in Markdown en vervolgens in HTML voor publicatie.

Tabel: toewijzing van conventionele commit-typen aan toon-frasing

Commit-type | Ontwikkelaar-frasering-voorbeeld | Klant-frasering-voorbeeld feat | Toegevoegde ExportCSV-methode aan ReportService die rijen naar een CSV-bestand streamt om geheugengebruik te verminderen. | U kunt nu rapporten rechtstreeks vanuit de export-knop als CSV-bestanden downloaden. fix | Opgelost deadlock in JobQueue.Push wanneer een nil-werk onder hoge belasting in de wachtrij werd geplaatst. | Taken zullen niet langer vastlopen wanneer het systeem druk is. perf | Vervangen van O(n²)-zoekopdracht in TagIndex.Find door een hash-kaart, waardoor de latentie van 12 ms naar 0,8 ms voor 10.000 tags wordt teruggebracht. | Tag-zoekopdrachten zijn nu merkbaar sneller, vooral met grote bibliotheken. refactor | Geëxtraheerd PasswordValidator-interface uit AuthHandler om regelbare sterkte-regels toe te staan. | Wachtwoordvereisten kunnen nu worden aangepast zonder de core-login-code te wijzigen. docs | Bijgewerkt API.md met nieuwe PATCH /users/:id-eindpunt-beschrijving en voorbeeld-payload. | Het helpcentrum toont nu hoe u een gebruikersprofiel gedeeltelijk kunt bijwerken.

SemVer-betekenis behouden over tonen heen

Regels voor versie-updates blijven gekoppeld aan commits

Het SemVer-label wordt uitsluitend bepaald door de conventionele commit-typen in de groep: een feat trigger een kleine update, een fix een patch en een brekende wijziging een grote update. Omdat de toonvoorkeuren de commit-berichten of hun typen niet wijzigen, is het resulterende versienummer identiek, of je nu de ontwikkelaars- of de klantversie leest.

Contractconsistentie

Ik behandel het SemVer-label als het contract tussen de producent en de consument van de software. De changelog is slechts een door de mens leesbare uitdrukking van dat contract. Door het contract ongewijzigd te houden, kunnen teams vertrouwen op geautomatiseerde tools (zoals release-bots of afhankelijkheidscontroleurs) om de versie correct te interpreteren, terwijl de dual-tone changelog de twee doelgroepen bedient zonder ambiguïteit te creëren.

Voorbeeld van een grote release

Stel dat een commit BREAKING CHANGE: verwijder legacy v1 API toevoegt. De ontwikkelaarsvoorkeur zal de exacte bestandsverwijderingen en de migratiestappen die nodig zijn, noteren. De klantvoorkeur zal uitleggen dat het oude API-eindpunt niet langer beschikbaar is en gebruikers doorverwijzen naar de v2-documentatie. In beide gevallen gaat de versie van 2.4.1 naar 3.0.0, waarmee de contractuele betekenis behouden blijft.

Wat dit niet is

Ik wil duidelijk zijn over de beperkingen van deze aanpak, zodat u realistische verwachtingen kunt hebben.

- Het garandeert niet dat elke gegenereerde zin perfect is qua toon; af en toe kan over-technische formulering in de klantontwerp terechtkomen, of vaag taalgebruik in de ontwikkelaarsontwerp. Menselijke controle is nog steeds vereist. - Het is geen 100 % vervanging voor een gewijd technisch schrijver of productmarketeer. De AI versnelt de eerste versie, maar nuances, merkstem en juridische mededelingen hebben nog steeds een menselijke aanraking nodig. - Het elimineert niet de behoefte aan duidelijke commit-hygiëne. Als commit-berichten vaag zijn of geen conventionele commit-structuur hebben, zullen de groepen minder nauwkeurig zijn en de uitvoer minder nuttig. - Het is geen magisch hulpmiddel dat automatisch elke regulator of toegankelijkheidsrichtlijn zal bevredigen. De veiligheidscontroles die ik heb toegevoegd zijn basis; u moet nog steeds uw eigen compliance-review uitvoeren. - Het belooft niet dat de changelog nooit een wijziging zal missen. Als een commit wordt weggelaten uit de git-log-bereik (bijvoorbeeld vanwege een ondiepe kloon of een verkeerde filter), zal deze niet in een van de tonen verschijnen.

Referenties

- OWASP LLM Top 10 - NIST AI Risk Management Framework

Verwante artikelen

- Gegroepeerde changelogs van commits (niet de raw git log) — Changelog AI - De LX AI Micro-SaaS Topic Matrix