Kuidas kirjutada muudatuslogi (ja väljalaskemärkmeid), mida kliendid loevad

autor: Fraser Hardy

Ühendatud pull requestid liiguvad läbi filtri kuupäevastatud muudatuslogisse, kus on kirjed Uus, Täiustatud ja Parandatud

Sa tõid eelmisel kuul välja tosin asja. Sinu muudatuslogi ütleb “Veaparandused ja jõudluse täiustused.”

Kliendid, kes ootasid ühte neist parandustest, ei tea, et see on valmis. Huviline, kes võrdleb sind konkurendiga, näeb toodet, mis näib kevadest peale paigast liikumata.

Siin on, kuidas kirjutada muudatuslogi, mida inimesed päriselt loevad. Kirjuta kliendile, mitte inimesele, kes koodi ühendas. Kuupäevasta iga kirje. Rühmita muudatused pealkirjade Uus, Täiustatud ja Parandatud alla. Alusta iga kirjet sellega, mida keegi nüüd teha saab, lisa üks rida selle kohta, miks see oluline on, ja ütle, kust seda leida. Jäta välja kõik, mida klient ei näe, ja kõik, mis pole veel töös. Seejärel avalda ühtlase rütmiga, isegi kui mõned nädalad on lühikesed.

See on peaaegu kõik. Ülejäänud postitus on mall, hulk halbu ja häid näiteid ning rutiin ühendatud PR-idest avaldatud märkmeteni jõudmiseks, ilma et see su reedet ära sööks.

Muudatuslogi ja väljalaskemärkmed: mis vahe on?

Inimesed kasutavad neid sõnu vaheldumisi, kuid tegelikult on kaks sihtrühma.

Arendajate muudatuslogi on tavaliselt CHANGELOG.md repositooriumis. See on mõeldud inimestele, kes integreeruvad sinu API, SDK või teegiga. Neid huvitavad versiooninumbrid, tagasiühildumatud muudatused ja iganenud osad. Keep a Changelog on siin standardne viide ja selle konventsioonid on mõistlikud: uusim esimesena, üks jaotis versiooni kohta, muudatused rühmitatud kui Added, Changed, Deprecated, Removed, Fixed ja Security ning ülaosas jaotis “Unreleased” töö jaoks, mis on ühendatud, kuid mitte välja lastud.

Väljalaskemärkmed (või “tooteuuendused” või avalik muudatuslogi leht) on mõeldud klientidele, kes toodet kasutavad. Neid ei huvita, et sa tõstsid sõltuvuse versiooni. Nad tahavad teada, mida nad nüüd teha saavad, mida eelmisel nädalal ei saanud.

Kui sa juhid SaaS-toodet, vajad tõenäoliselt teist rohkem kui esimest. Paljud meeskonnad vajavad mõlemat ja see on okei: üks ühendatud töö nimekiri võib toita kahte kirjutist. Lihtsalt ära avalda arendajaversiooni ja nimeta seda väljalaskemärkmeteks.

Väljalaskemärkmete mall, mida saad kopeerida

See sobib iganädalaseks või kahenädalaseks tooteuuenduseks, muudatuslogi lehel, rakendusesiseses vidinas või e-kirjana.

## 6 October 2026

### New
**[What you can now do, in plain words]**
[One or two sentences: what it does and who it's for.]
Find it in **[Page > Section]**. [Link to help article]

### Improved
**[The thing that got better]**
[What's different from before, in terms the customer notices:
faster, fewer clicks, works on mobile, handles bigger files.]

### Fixed
- [Symptom the customer saw], now fixed.
- [Symptom the customer saw], now fixed.

### Heads up (only if needed)
**[Anything changing or going away]**
[What's happening, when, and what they need to do.]

Mõned reeglid, mis selle tööle panevad:

Halvad ja head muudatuslogi kirjed

Halb muudatuslogi kirje, mis on kirjutatud commit-sõnumitena, ja selle kõrval hea kirje, mis selgitab, mis kliendi jaoks muutus ja kust seda leida

Kõige levinum viga on commit-sõnumite kleepimine. Siin on, kuidas see välja näeb:

v2.14.0
- feat(export): csv async job
- fix: tz bug in reports
- refactor billing svc
- bump deps
- misc improvements

Kõik seal on tõsi. Mitte miski ei ole kliendile kasulik. Kaks kirjet on sisemine müra, üks on tähenduseta (“misc improvements”) ja kaks tõelist muudatust on kirjutatud sellele, kes PR-i üle vaatas.

Siin on sama väljalase ümber kirjutatuna:

6 October

NEW: Big CSV exports run in the background
Exports over 10,000 rows no longer time out. Start the export
and we'll email you a link when the file is ready.
Find it in Reports > Export.

FIXED: Report dates now match your timezone
Daily totals were splitting at midnight UTC instead of your
local midnight, so some days looked short. They're correct now,
including for past reports.

Viie kirje asemel kaks. Kumbki ütleb, mis muutus, miks lugeja peaks hoolima ja kuhu vaadata. Ümberkorraldus ja sõltuvuse versiooni tõstmine on kadunud, sest ükski klient ei märka neid.

Veel mõned paarid, sest muster võtab aega harjumuseks muutumiseks:

HalbHea
Lisatud SSOLogi sisse Okta või Google Workspace’iga. Adminid saavad selle sisse lülitada jaotises Seaded > Turvalisus.
Parandatud jõudlustTöölaud laadib suurtel kontodel palju kiiremini. Tuhandete üksustega projektid ei venita enam esmakordsel laadimisel.
Parandatud teavituse vigaSa ei saa enam topeltkirju, kui keegi mainib sind ühes kommentaaris kaks korda.
Iganenud v1 lõpp-punktidV1 API lakkab töötamast 1. märtsil. Ürita enne seda üle v2-le. Siin on, mis muutub.

Pane tähele, et “palju kiiremini” on ebamäärane. Kui sul on päris mõõdetud number, kasuta seda. Kui ei ole, kirjelda kogemust, mitte ei mõtle protsenti välja.

Kuidas kirjutada muudatuslogi ühendatud PR-idest

Viiesammuline muudatuslogi töövoog: kogu ühendatud PR-id, filtreeri kliendile nähtavad ja töös olevad muudatused, rühmita tüübi järgi, kirjuta kliendile ümber, avalda linkidega

Enamik meeskondi ei võitle kirjutamisega. Nad võitlevad meelespidamisega, mis välja läks. Siin on rutiin, mis peab vastu.

1. Kogu. Loetle kõik, mis on pärast viimast kirjet ühendatud. GitHubi CLI-ga:

gh pr list --state merged \
  --search "merged:>=2026-10-27" \
  --json number,title,labels,mergedAt,url \
  --limit 100

2. Filtreeri. Küsi iga PR-i kohta kaks küsimust. Kas klient saab seda näha või tunda? Kas see on neil tegelikult töös? Sisemised ümberkorraldused, CI muudatused ja testiparandused lähevad ära. Samuti kõik, mis on funktsioonilipu taga, mida pole sisse lülitatud. Tööst teatamine, millele kliendid veel ligi ei pääse, on halvem kui mitteteatamine, sest saad “kus see on?” piletid.

3. Rühmita. Sorteeri, mis alles jääb, rubriikidesse Uus, Täiustatud ja Parandatud. Mitu väikest PR-i moodustavad sageli ühe kirje (“Hulgimuutmine” võib olla neli PR-i).

4. Kirjuta ümber. Muuda iga rühm malli kasutades kirjeks. Kasu esimesena, lihtsad sõnad, kust leida.

5. Avalda ja lingi. Postita see, lingi iga uus funktsioon selle abiartiklile ja jaga seda kõikjal, kus sinu kliendid seda näevad.

Trikk, mis teeb sammu 4 palju lihtsamaks, on küsida kliendile suunatud lause PR-i ajal, kui autor veel mäletab, mida ta ehitas. Lisa jaotis faili .github/pull_request_template.md:

## Customer-facing change
<!-- One sentence a customer would understand, or "None". -->
<!-- e.g. "You can now export reports over 10,000 rows." -->

- [ ] Behind a feature flag (don't announce until it's on)
- [ ] Help articles checked

See viimane märkeruut on oluline. Iga välja läinud muudatus, mis puudutab kasutajaliidest, võib jätta abiartikli aegunuks ja muudatuslogi on hea hetk see üles leida. Käsitleme seda poolt artiklis kuidas dokumentatsiooni ajakohasena hoida.

Kui tihti peaksid tooteuuendusi avaldama?

Sobita oma väljalaskerütmiga, mõistlikes piirides. Kui annad välja pidevalt, loeb iganädalane või kahenädalane kokkuvõte paremini kui kirje iga juurutuse kohta. Kui annad välja kord kuus, avalda kord kuus.

Olulisem kui sagedus on järjepidevus. Muudatuslogi, kus on jaanuaris kolm kirjet ja pärast seda mitte midagi, ütleb külastajatele midagi, mida sa tõenäoliselt ei mõelnud öelda. Lühike nädal on okei. “Kaks parandust sel nädalal, suurem väljalase järgmisel nädalal” on parem kui vaikus.

Suured lansseerimised väärivad rohkemat kui muudatuslogi rida: korralikku teadaannet, e-kirja, võib-olla lühikest videot. Muudatuslogi on jooksev kirje, mitte kogu turundusplaan.

Kuhu muudatuslogi panna

Spetsiaalsed tööriistad nagu Beamer, Headway, LaunchNotes või Canny muudatuslogi tegelevad vidina ja e-posti poolega hästi. Paljud meeskonnad kasutavad lihtsalt lehte oma dokumentatsioonisaidil. Tööriist on harjumusest vähem oluline.

Kus Ellie Docs sobib

Avalikustamine: see on probleem, mille jaoks me midagi ehitasime. Ellie Docs jälgib sinu ühendatud PR-e ja koostab neist muudatuslogi kirjeid, mis on kirjutatud klientidele, mitte ülevaatajatele. See jätab väljalaskmata kirjed töö kohta, mis on väljaandmata või lipu taga, et sa ei teataks asjadest, mida inimesed kasutada ei saa. Sina muudad, jätad välja või avaldad iga kirje. Miski ei lähe ise välja.

Ellie Docsi muudatuslogi vaade klientsõbralike kirjetega, mis on koostatud ühendatud pull requestidest, igaüks lingitud abiartikliga, millega see seotud on, valmis muutmiseks või avaldamiseks

Kuna see hooldab ka sinu abikeskust, toodab sama PR, mis annab muudatuslogi kirje, soovitatud uuenduse igale artiklile, mis on nüüd aegunud, kuvatuna diffina, mille sa kas aktsepteerid või lükkad tagasi.

Soovitatud abiartikli uuendus pärast pull requesti, kuvatud punase ja rohelise diffina nuppudega Aktsepteeri ja Lükka tagasi

Kui sinu muudatuslogi on praegu commit-pealkirjade nimekiri või seda pole alates lansseerimisest puudutatud, on see lünk, mida see täidab. Kui sulle meeldib seda käsitsi kirjutada, viivad ülaltoodud mall ja PR-i kontrollnimekiri sind enamiku teest.

Mõned levinud küsimused

Kas muudatuslogi peaks sisaldama veaparandusi? Jah, neid, mida kliendid märkasid. Parandus vea kohta, mida keegi teatas, on üks enimloetud asju, mida avaldada saad, eriti kui ütled sellest inimesele, kes teatas. Jäta vahele parandused asjadele, mida keegi väljaspool meeskonda kunagi ei näinud.

Kas mul on versiooninumbreid vaja? API, SDK või millegi installitava puhul jah ja järgi semantilist versioonimist, et inimesed saaksid riski ühe pilguga hinnata. Pidevalt juurutatava veebirakenduse puhul on kuupäevad selgemad. Kliendid ei mõtle versioonides.

Kui pikk peaks muudatuslogi kirje olema? Paks pealkiri pluss üks kuni kolm lauset. Kui vajad rohkem, kirjuta abiartikkel või blogipostitus ja lingi sellele.

Tahad oma muudatuslogi koostada juba ühendatud PR-idest? Proovi Ellie Docsi tasuta. Tasuta plaan on olemas ja kaarti pole vaja.