How to write a changelog users actually read: release notes for vibe projects

Why your project needs a changelog

Many vibe projects die in a quiet place: not from too few features, but from nobody knowing they got better. A user opens your project, sees the last update was three months ago, and their first thought is not "this project is stable" but "is this project still maintained?" A changelog is the cheapest tool against that misjudgment: a few lines telling everyone the project is alive, what changed last week, and what changed this week.

A changelog has a second job: keeping your own books. Vibe coding moves fast — several releases a day are normal — and a month later you yourself will forget when a feature was added or when a bug was fixed. Without a log, every time a user asks "when did this feature appear," you have to dig through commit history. With a log, the answer is on one page. Writing a log is not vanity for others; first of all, it is a memo to yourself.

The third job is the easiest to underestimate: a changelog is a source of user trust. When users decide whether to build your little tool into their workflow, they look at two things: whether it was updated recently, and whether the updates are written clearly. A carefully written log says, "I take responsibility for my changes, and I dare to explain each one." That sentence is worth more than any slogan on your homepage.

Pick a format, then never change it

The worst sin of a changelog is changing style every time. One week you write "added export," the next week "v0.3.2," the week after a long essay — users cannot scan that. Once a format is set, keep it as stable as an API, because users read logs by pattern recognition: eyes sweep for the version number first, then the date, then keywords like "added" and "fixed."

The format I recommend is simple: each release starts with four things — version number, release date, a one-line summary, and categorized entries. Use four fixed categories: Added, Improved, Fixed, and Other. Added is for features that did not exist; Improved is for existing features that got better; Fixed is for bugs that are gone; Other holds migrations, documentation, and internal changes users care less about but you want on record. Four categories are enough — more categories mean more agonizing for the writer and more confusion for the reader.

How to version? For a personal project, semantic versioning is the least-effort choice: a major version means incompatible changes, a minor version means new features that stay compatible, a patch means bug fixes only. You do not need to apply it perfectly to every commit, but users should be able to tell from the version number roughly whether an update needs care. If you do not want to think about it at all, use date versions like 2026.11.04 — simple, honest, and never wrong.

How to write a single good entry

A good entry passes one test: after reading it, the user knows "what does this mean for me?" The bad example is: "Optimized several logics and improved system stability." That sentence is not wrong; it is true of every project and every release, which means it says nothing. After reading it, the user still does not know: should I update? What will be different? What do I lose if I do not?

A good entry follows "action + object + impact on the user." For example: "Export now supports CSV format; exported tables open directly in Excel, with no manual conversion." That sentence has an action (supports CSV), an object (export), and an impact (no manual conversion). A user can decide in three seconds: this update matters to me; I will update.

Fix entries need their impact range spelled out even more. Do not just write "fixed a crash"; write "fixed a crash when exporting more than 1,000 rows; users who hit that crash can now export normally after updating." The first version makes users guess whether it was their crash; the second tells them directly that it was. Spending one extra minute on a fix entry can save several support emails.

And one iron rule: do not copy internal jargon into the log. A commit message saying "refactored auth middleware" is fine, but the log must translate it into user language: "the login page now loads faster; the occasional spinner issue is resolved." That translation step cannot be skipped, because the log's readers are users, not your commit history.

When to write: not on release day

The most common failure mode is this: one hour before release, the developer stares at dozens of commits trying to remember what changed this week, and ends up writing a vague "various improvements." The fix is to jot a line when the change happens, not to recall everything at release time. The lightweight method: keep a CHANGELOG.md in the repo, with an "Unreleased" section at the top; every time a feature merges, add a line or two there.

The flow looks like this: during development, the top of the changelog always has an "Unreleased" section; each pull request adds a line or two to it; at release time, rename "Unreleased" to the version number and date, and start a new empty "Unreleased" section. The cost of writing is spread across every change — one minute each — and release time needs zero recall and zero pain.

If you develop with AI assistance, you can let the AI draft log entries, but remember two things. First, the AI can only draft from commit history; it does not know what a change means for users, so you must add the "what it means for the user" half yourself. Second, AI-drafted entries must pass your human check, because AI will confidently invent features that do not exist — and a log entry describing a nonexistent feature damages trust more than a log that is one day late.

Fictional example: what a decent changelog looks like

Here is a fictional example (fictional, for format demonstration only, not a real project). Suppose you built a to-do tool called "Checklist Cat," and this release is v0.4.0:

Version v0.4.0, November 4, 2026. This release focuses on making export better, and fixes two bugs users reported repeatedly. Added: export supports CSV format; exported tables open directly in Excel. Improved: lists with more than 50 items no longer stutter when scrolling. Fixed: fixed a crash when exporting more than 1,000 rows; fixed completed tasks being hard to read in dark mode. Other: upgraded underlying dependencies; security patches are in sync.

Notice the traits: every entry has action, object, and impact; fix entries name their trigger conditions (more than 1,000 rows, dark mode) so users can match them; there is not a single empty phrase like "various improvements" or "experience upgrades." A user can read it in thirty seconds and decide whether to update — and that is a changelog's entire job.

Big releases deserve more words; small ones do not

Not every release deserves an essay. A patch fixing one small bug needs two lines. A major release that changes the interface, changes the data model, and requires migration must say more — and the migration guide must come first in the log. What users fear most is not the update itself, but discovering after updating that their data or habits broke, with nobody warning them in advance.

The structure I suggest for a major release: one sentence saying what the big change is, then "if you are an existing user, here is what to watch for," then the regular categorized entries. Put the warnings first because many users only read the first three lines — anything important buried at line ten might as well not be written.

One more detail: features removed in a major release must be stated plainly, not hidden. Writing "the old export entry was removed; please use the new export" is far more dignified than letting users discover the entry is gone. Users can accept a feature being removed; they cannot accept it being removed quietly. The first is a decision; the second is an accident.

Where to put the log so users actually see it

A well-written log in the wrong place is the same as no log. The three safest places: a visible "Changelog" entry in your project's homepage or navigation, a CHANGELOG.md at the repo root, and release notes attached to each release. These serve three kinds of users: passing visitors, developers checking the code, and existing users who already installed the product.

For a vibe project, I suggest at least the first two: reachable from the website, and a file in the repo. Release notes can reuse the same content without rewriting. Remember the principle: the shorter the path for a user to find the log, the more valuable the log is. If finding update records takes three layers of menus, users will give up and judge your project "unmaintained" on gut feeling.

Also, keep the log page itself lightweight: plain text or simple formatting is enough. Do not add animations and images for the sake of "looking nice." Users come here to check information, not to admire design. Fast loading, searchable, readable on a phone — those three beat any visual effect.

Common mistakes checklist: check before you publish

Mistake one: version number and date only, empty body. That tells users "I updated, but I will not tell you what changed" — worse than not writing at all. Mistake two: pasting raw commit messages, full of "fix typo," "wip," and "update" that only the author understands. Mistake three: padding with empty phrases like "various improvements" or "experience upgrades" that leave readers knowing nothing.

Mistake four: only good news, no fixes, as if the project never had bugs. Users are not naive — fix records are precisely the evidence that a project is seriously maintained, and hiding them looks evasive. Mistake five: major releases without migration notes, leaving existing users to figure out the new interface themselves. Mistake six: three months of silence, then one long catch-up post — that shows the log was not kept along the way, and readers can tell at a glance.

Check against these six, and your log already beats most small projects. Competition in this area is genuinely weak: write consistently and clearly, and you have already won.

Bilingual projects: how to split Chinese and English logs

Many vibe projects serve both Chinese and English users — should the log be written twice? My suggestion: core releases in both languages; patch releases can carry one full version plus a one-line summary in the other language, depending on who your main users are. The key failure to avoid is "the Chinese log stopped three months ago while the English one updates weekly" — that makes one side feel like second-class users.

Bilingual writing has its own rule: do not translate word for word; rewrite in each language's habits. Chinese readers like to see "what changed for me" first; English readers like the version and date first. The structure can match, but sentences should follow native habits. If your English is shaky, write the English version shorter and simpler rather than machine-translating a long, awkward essay — short and correct English is more dignified than long and broken English.

One time-saving method: write the full version in Chinese, and a condensed English version keeping only the categorized entries and impact notes, skipping background explanations. The one hard requirement for bilingual logs: version numbers and dates must match on both sides. If versions do not match, the bilingual log loses its value as a reference.

After a year of logs: archiving and review

After a year, the log file gets long. Two things to do: archive and review. Archiving means folding or paginating versions older than a year, so new users opening the log page do not first see last year's content — new users care about the last three months; old content should be reachable, not in the way.

Review means spending half an hour at year-end reading the year's log from start to finish, to see how far the project actually came. You will find surprises: the feature users complained about in spring was fixed by summer; the goal set in January was actually delivered by December. That review can become a year-end summary posted on the blog or homepage — an account to users, and encouragement to yourself.

More importantly, review reveals problems in the log itself: three months unwritten? Some category always vague? Questions users keep asking that the log already answered, but nobody found? The answers are next year's improvements. A log is not a write-and-forget file; it is part of the project's memory, worth revisiting regularly.

One last thought: the bar for changelogs is so low that anyone can start today, and the payoff is high enough to directly affect users' first impressions. It needs no new tools, no refactoring — just a habit: when a change happens, write one line in plain language. Vibe coding made writing code faster, but it did not make earning user trust faster. Trust still accumulates one clear explanation at a time.