Release Notes Are a Letter, Not a Log: How Vibe Projects Should Announce Updates

Release notes are not a copy of the changelog: they are a letter to users

Many vibe projects' release notes read like a machine-generated list: "Fixed several bugs, improved performance, enhanced the experience." Users finish reading without knowing what changed, how it affects them, or whether to bother opening the app again — and next time they stop clicking. The real readers of release notes are three groups: current users (who want to know "what does this update do for me"), people on the fence (who want to know "is this project still being properly maintained"), and future you (who wants to know "why was this changed back then"). Something written for those three groups was never going to be the same document as the commit history. This article explains how release notes should be written, what structure to use, and which phrases to avoid, plus a template you can apply directly. The example project "Ledger Buddy" and its versions and changes are fictional, used only to demonstrate the writing.

Start with a test: good release notes let a user answer three questions after reading — what changed, how does it affect me, and do I need to do anything? What changed must name features specifically, not hide behind "several", "some" or "related". The effect must land in a usage scenario, not a technical term. What to do must be stated explicitly, including "you don't need to do anything" — telling users explicitly that no action is needed is itself useful information. Conversely, if users finish reading still unsure whether to update or what to watch for, the notes have failed, however many items they listed.

Structure: four fixed sections, in shrinking length

The recommended structure has four sections in a fixed order, each shorter than the last. First, a one-sentence overview: the core change of this version, in words users understand. For example: "Version 2.3 adds monthly comparison to reports, so you no longer need to export data and calculate it yourself." One sentence, no preamble, no "we are delighted to announce". Second, "New features": one or two sentences per feature, saying what it does and where to find it. Third, "Fixes and improvements": only fixes users can feel — misaligned interfaces, crashes, wrong numbers. Pure internal refactoring or dependency upgrades, which users cannot perceive, do not belong here, or can be folded into one line about "some internal tidying". Fourth, "Please note": anything users will trip over if they do nothing — re-login required, data migration, a retired feature, a price change. Everything in this section must sit somewhere visible, not buried at the end.

This structure has one great benefit: it forces choices. A vibe project's update often touches many places, and AI-generated commit lists can run to twenty or thirty items, but users care about three to five of them. The filter is "user perception": can users feel the change when they open the app? If yes, write it; if no, leave it out. A second filter is "risk": could the change break a user's existing way of doing things? If yes, it must go into "Please note", however small it looks. Many reputation accidents happen because a "please note" was dressed up as an "improvement": users update, find an old feature gone, and their first reaction is not "oh, it changed" but "this thing broke my stuff".

Writing: plain words, a scenario, and a scope

Plain words, rule one: do not use developer-only terms, or explain them immediately if you do. "We refactored the billing aggregation layer" is worse than "reports open faster — what used to take three seconds now feels instant". Rule two: give a scenario. Do not just name the feature; say when users will use it. "Added monthly comparison" is weaker than "at month-end reconciliation, you can now see directly how much more you spent this month than last, without exporting a spreadsheet". Rule three: mark the scope. Does this change affect all users, or only users of one feature? Stating scope lets users judge whether to read carefully. For example: "This update only affects users who sync via iCloud; everyone else is unaffected" — one sentence saves 90% of readers' time.

Several kinds of sentence should simply be deleted. The first is empty talk: "we are constantly working to improve your experience", "thank you all for your support" — noise in release notes; thanks belong in a single closing line, not in the body. The second is technical boasting: "built on the latest architecture" — users do not care about architecture names, only outcomes. The third is vagueness: "several", "some", "related optimisations" — behind every vague word is something the author did not actually pin down. A self-test while writing: read the notes aloud to a friend who has never used the product. If they can repeat back "what changed and how it affects me", it passes; if not, keep editing.

Version numbers and rhythm: let users tell at a glance how big an update is

A version number is itself a communication tool, provided it has rules. The commonest scheme has three parts: major (breaking changes or major features), minor (new features, compatible), patch (fixes only). Moving from 2.2 to 2.3 tells users "new features, no need to relearn"; from 2.3 to 3.0 tells them "something may need adapting". The key is consistency: do not use 2.3.1 for a major rewrite one time and 3.0 for a typo fix the next. Vibe projects, updating frequently, are especially prone to casual versioning — AI-suggested version numbers often follow no consistent scheme, and developers adopt them without thinking. Write down one simple rule for the project and follow it in every release note; users will gradually build expectations around it.

Release rhythm deserves its own rule too. Frequent small updates and saved-up big updates each have trade-offs: small updates are easy to absorb but their notes easily become a running log; big updates tell a story but change so much at once that problems are hard to locate. A practical rhythm for a solo vibe project: ship fix-only patches whenever they are ready, with a single sentence each; save feature updates until they can be summarised in one sentence — "reports gained monthly comparison" is a version on its own. Do not force versions to look active, and do not hoard three months of features into one unreadable essay. The length of release notes should track the size of the update's effect on users.

Channels: one set of facts, three different writings

The same release notes need different shapes in different channels. In-app update prompts should be shortest: a one-sentence headline, three to five bullet points, and a "see details" link — nobody reads an essay in a popup. The website or blog post can be longest: background, why the feature was built, a couple of screenshots, for users who want depth. Social media should be punchiest: one sentence on the core change, one image, one link — never paste the full list. Three channels share the same facts but differ in length and tone; that is not duplicate work, it is adaptation to different reading situations. Many projects write one version and paste it everywhere, ending up with an essay in a popup and a checklist on social media — unreadable in both places.

One channel is easy to overlook: email or in-app messages to lapsed users. Their job is not notification but recall: telling people who have not opened the app for a while that "the problem you reported is fixed" or "the feature you asked for is live". That message is the opposite of release notes: do not list everything, mention only the one or two items relevant to that recipient. For example, telling users who asked for report comparison that "monthly comparison is live — find it at the top right of the reports page" beats blasting everyone with the full notes. The precondition is genuinely recording user feedback by theme, not leaving it scattered across chat logs.

Template and pre-publish checklist: fill it in, then ship

Here is a template to apply directly. Title format: version plus a one-sentence core change, for example "2.3: reports gain monthly comparison". Body paragraph one: a one-sentence overview. Paragraph two: new features, each in the form "feature name: scenario + location", for example "Monthly comparison: at month-end reconciliation, see this month's difference from last month directly, at the top right of the reports page". Paragraph three: fixes and improvements, only user-perceptible items, each stating "how it was before, how it is now". Paragraph four: please note, listing every item requiring user action, or "this update requires no action" if there is none. Close with a feedback channel (email or form link) and, if there is one, a one-sentence preview of the next version.

Before publishing, run this checklist: does the title carry the version and the core change; does each new feature carry a scenario and a location; are the fix items user-perceptible; does "please note" miss any item requiring user action; do vague words (several, some, related) need replacing with specifics; has technical jargon been translated into plain words; are the three channel versions prepared separately? Ship only when all pass. Well-written release notes buy more than "users know what changed": they build a longer-term asset — users start to believe that every update here was thought through. That trust is the key step between a vibe project that "runs as a demo" and one "worth using long term".

Five common bad release notes to avoid

Five anti-patterns are worth checking your own project against. The first is the riddle: "This update includes various improvements and bug fixes." It says nothing; short is not the problem, zero information is. The second is the technical report: "refactored the billing aggregation layer, upgraded dependencies, optimised query plans" — developers understand it, users do not; release notes are for users, not code review. The third is the running log: twenty or thirty commit records pasted verbatim, forcing users to scroll three screens to find the one item relevant to them. The problem is not wrong content but missing judgement — choosing is the author's job, not the reader's.

The fourth is "good news only": new features described lavishly while changes users need to know about — a retired feature, a changed free allowance, a new login method — go unmentioned. When users trip over them after updating, the first feeling is deception, and the trust lost far exceeds the feature's value. The fifth is "emotion overflow": the whole text about how hard the team worked and how grateful they are, with the actual changes taking two lines. Gratitude is fine, but release notes are not thank-you letters; keep emotion to one sentence and leave the rest for facts. All five share one root cause: the author wrote thinking "I need to account for what I did" instead of "what does the user need to know". Changing the subject from "I" to "you" fixes most of it by itself.

Going further: using release notes as product communication

Once release notes reach a decent standard, they can carry more communication work. First, the "why": not just "added monthly comparison" but "many users told us month-end reconciliation meant exporting spreadsheets, so we added monthly comparison". One sentence of background makes users feel heard and lets onlookers judge whether the project listens. Second, trade-offs: sometimes shipping one feature means adjusting another, for example "to make reports open faster, we have temporarily retired PDF export while we rebuild it; it returns next version". Stating a trade-off openly earns understanding; hiding it until users discover it themselves turns it into "a feature was secretly cut".

Third, accumulate an update history as a trust asset. Keep every release note on one dated page on the website; after a few months it becomes a public record of the product's evolution — new users can see at a glance whether the project is actively maintained, how often it updates, and whether each update says anything real. That matters especially for vibe projects, where users naturally wonder "will this still be maintained next month". A steady, specific, honest update history is the cheapest way to answer that doubt. Conversely, a history full of "fixed several issues" only deepens it. Fourth, close the loop with feedback: after each release, actively collect reactions to it, note them, and respond next time — "the issue many of you raised last time is fixed in this release". Release notes then stop being one-way announcements and become an ongoing conversation — and conversation is what keeps small projects' users around.

A special note for AI-assisted writing: do not let AI publish your release notes unchecked

Vibe-project authors easily make one mistake: letting AI generate release notes from commit history and publishing them unchecked. AI drafts usually have two problems. First, they list everything regardless of user perception, because the model has no "user perception" filter. Second, they paper over gaps with vague words — "improved the related experience" — a sentence with no corresponding commit, invented purely as connective tissue. The right workflow is to treat AI as a first-draft tool: let it organise a list from commits, then apply the two filters yourself — user perception and risk — rewrite it in plain words, and delete vague terms. AI can write the first draft; the final draft must pass through a human. Release notes are the product speaking in public, and once words are out they cannot be taken back. Ten minutes saved here can easily cost ten hours in support later.

One more detail: AI-generated notes often "invent" changes that never happened — a planned feature written as shipped, or a refactoring written as a performance gain. Before publishing, verify every item against fact: is each new feature really in this version, is each fix really fixed, is each number really measured? The check is simple: open the app and walk the path the notes describe, item by item. It takes less than ten minutes and catches most factual errors. Remember, every error in release notes costs a point of trust at the user's end, and trust is the resource a small project can least afford to burn.