The changeloop blog
Release notes, in practice
Two things we think about a lot: how to write release notes anyone reads, and how to stop maintaining a changelog by hand. No newsletter, no gate. Just the writing.
Release notes practice
How teams write release notes people actually read.
-
Software release notes: what they are and what to include
Software release notes tell a reader what changed in a version, who it affects and what to do. The four kinds, what to include, and a worked example.
Release notes practice5 min read
-
Bug fix release notes: how to write entries people use
Bug fix release notes work when each entry names the symptom, who was hit and the next step. Before and after rewrites, plus security and data-loss rules.
Release notes practice7 min read
-
Release notes examples for every kind of change
Release notes examples for a feature, fix, breaking change, security fix, deprecation, app store note and internal note, each with why the wording works.
Release notes practice7 min read
-
Emergency release notes: writing under real time pressure
An incident-driven release needs notes written in minutes, not days, and the usual drafting process assumes time you don't have. What to keep, what to cut.
Release notes practice5 min read
-
Internal release notes: who else needs to know what shipped
Support and sales usually learn about a launch from a confused customer. Internal release notes fix that, in a different shape from customer-facing ones.
Release notes practice5 min read
-
Release notes for mobile apps: what the limit cuts
App Store and Play Store give a few visible lines and no links. What works on a web changelog breaks on that budget, so every cut has to be deliberate.
Release notes practice5 min read
-
How to announce a new feature (without the silence)
Most feature announcements die in a channel nobody reads twice. Where to announce, what to say first, and how to reach the people who asked for it.
Release notes practice5 min read
-
Enterprise release notes: what changes for one account
Enterprise release notes for a customer on a private build must be scoped to their instance. Get the scoping wrong and you leak roadmap or confuse support.
Release notes practice5 min read
-
What is a changelog, and what goes in one?
A changelog is the dated record of what changed in a product, written for the people affected by it. What it is, is not, and where a good one lives.
Release notes practice5 min read
-
The product update email template that gets read
The email that gets read is the one sent to somebody who asked. The template, the four kinds of update email, subject lines, segmentation and consent.
Release notes practice6 min read
-
Changelog vs release notes: what is the difference?
A changelog is a running record for people looking something up. Release notes are a curated message for people deciding whether to care. How they differ.
Release notes practice5 min read
-
How to write release notes people actually read
Bug fixes and performance improvements is not a release note. Here is the question every entry has to answer, and a before and after rewrite of a real one.
Release notes practice6 min read
-
Release notes best practices worth keeping
Most best practice lists for release notes are style advice. These are the ones that change what a reader does, and three popular ones that are cargo cult.
Release notes practice6 min read
Engineering
Changelogs as a build artifact: conventions, automation, pipelines.
-
Release candidate (RC): what it means and how to run one
A release candidate is a build that ships as the final version unless testing finds a blocker. Where RC sits after beta, how to version it, and exit rules.
Engineering5 min read
-
CHANGELOG.md: what goes in it and how to keep it current
A CHANGELOG.md is the reader-facing record of what changed in each version. The sections it needs, a full example, and the one habit that keeps it current.
Engineering6 min read
-
GitHub release notes: generate them, then make them readable
GitHub can draft release notes from merged pull requests in one click. What it holds, how release.yml shapes it, and the edit pass that makes it readable.
Engineering6 min read
-
Release management process for teams that ship often
A release management process for software teams in seven steps, with an owner and exit criteria for each, plus the DORA metrics and one more KPI to track.
Engineering7 min read
-
Who writes the changelog, and who should
Who writes the changelog? The PR author knows what changed; the PM knows why it matters. Neither alone writes an entry customers can actually use.
Engineering5 min read
-
Changelog file formats: JSON, YAML, or just Markdown
A changelog file's format decides whether it can feed a page and a widget, or only be read by a person. Markdown, JSON and YAML cost different things.
Engineering5 min read
-
A changelog check for GitHub Actions
A changelog check in GitHub Actions that refuses to merge without an entry, why relying on memory fails on a schedule, and what the check itself breaks.
Engineering5 min read
-
Git tags, releases, and your changelog
A git tag, a release, and a changelog entry are three records of one event. Conflating them is how a changelog drifts from what shipped. How they line up.
Engineering5 min read
-
Monorepo changelogs: one log, or one per package?
A monorepo can ship one changelog for the whole repo or one per package. Picking wrong makes releases either too noisy to read or too scattered to find.
Engineering5 min read
-
Semantic versioning and your changelog
Semantic versioning tells a caller how much a release can hurt before they read a word of it. What each number promises, and what an entry owes.
Engineering5 min read
-
How to build a changelog page people subscribe to
A changelog page is worth building when somebody returns to it. Where it lives, what an entry needs, feeds and markup, and how the widget fits alongside.
Engineering6 min read
-
Changelog automation, and its limits
Automate collection, formatting and publishing. Do not automate selection or wording. Here is where the line sits and what happens each time it moves.
Engineering6 min read
-
From conventional commits to a changelog
Conventional commits make a changelog derivable. They do not make it readable. Here is what the convention buys, where it stops, and how to bridge the gap.
Engineering5 min read
-
Keep a Changelog, actually implemented
The Keep a Changelog spec is one page and takes ten minutes to read. Implementing it is where teams drift. What it says, leaves open, and gets wrong.
Engineering5 min read
API changes
Breaking changes, deprecations and versioning, told to the people they affect.
-
REST API versioning: URL, header or query, which one fits
REST API versioning puts the version in the path, a header or the query string. What each means for callers, caches and announcements, with examples.
API changes6 min read
-
Stripe API versioning: how it works and what to copy
Stripe API versioning pins each account to a dated version and lets any request override it. How it works, what it costs, and what a small API can copy.
API changes7 min read
-
Protobuf breaking changes: what survives on the wire
Protobuf breaking changes happen on the wire, not in the URL. Some gRPC field changes are free, others break every client silently, and the two look alike.
API changes6 min read
-
GraphQL deprecation without a version number
GraphQL has no v1 or v2 in the URL. Fields get deprecated one at a time with a directive on one shared schema, which changes what a changelog owes callers.
API changes5 min read
-
How to write an API migration guide
An API migration guide turns a breaking change from an outage into a checklist. What it needs, when to publish it, and why a changelog entry is not enough.
API changes5 min read
-
Internal API changelogs: what changes for the other team
A public API changelog has an audience you can't reach directly. An internal one has an audience two floors away, and that changes what it owes them.
API changes5 min read
-
The API sunset header, and when to send one
The API Sunset header tells a client a version stops answering, unlike a deprecation notice. What RFC 8594 covers, and what a brownout buys you.
API changes5 min read
-
Webhook changelogs: the breaking change nobody requested
A webhook payload change breaks silently, because there is no caller to reject the new shape. What makes a payload change breaking, and how to version one.
API changes5 min read
-
API changelog: what to publish and who reads it
An API changelog is read by people deciding if their code still works next month. What each entry owes them, where it lives, and how callers subscribe.
API changes7 min read
-
API versioning best practices, for the callers' sake
Version only what breaks, put the version where callers can see it, and keep the old one running until a set date. Four schemes, compared by what they ask.
API changes7 min read
-
Breaking changes: what counts and how to ship one
A breaking change is any change a correct caller could not survive. What counts, what does not, how to catch one in CI, and how to ship it safely.
API changes9 min read
-
How to deprecate an API without losing its developers
Deprecation is a promise with a date on it. The timeline, the notice template, the response headers, and the step that stops a sunset becoming an incident.
API changes6 min read
Feedback loop
From request to shipped to told: feature requests, roadmaps, closing the loop.
-
Kano model: sort feature requests by how customers feel
The Kano model sorts features into must-be, performance and delighter groups using a two-question survey. How to run it on feature requests and read it.
Feedback loop6 min read
-
RICE scoring: formula, worked example and pitfalls
RICE scoring ranks ideas by reach, impact, confidence and effort. The formula, a four-feature worked example, scale values and the mistakes that skew it.
Feedback loop5 min read
-
How to build a product roadmap from customer feedback
How to build a product roadmap in six steps, starting from the requests you already have. Group, rank, label confidence and review it so it stays true.
Feedback loop5 min read
-
Product roadmap template: the fields to copy and fill
A product roadmap template is a table with fixed fields per item. Copy the six-field version, see it filled in, and learn which fields to cut.
Feedback loop6 min read
-
How to ask for customer feedback in a software product
Ask one specific question right after the user does something, where they are working. Ready-to-use wording for each moment, plus the bad asks to avoid.
Feedback loop7 min read
-
Product roadmap examples: six formats and how each fails
Six product roadmap examples with realistic items: Now/Next/Later, quarterly, theme, outcome, public and release. Who each suits and how each goes wrong.
Feedback loop7 min read
-
Duplicate feature requests: merging without losing the voice
Grouping duplicate feature requests protects the count. Merging them carelessly loses the wording that made one of them useful, which is the smaller loss.
Feedback loop5 min read
-
How to decline a feature request without losing the customer
Closing the loop usually means telling someone their request shipped. The harder half is telling them no, in a way that keeps the relationship intact.
Feedback loop5 min read
-
Feature flag release notes: what to say, and when
Feature flag release notes have to pick an event: merged or released. Close the loop on the wrong one and you announce a feature the user still cannot see.
Feedback loop5 min read
-
When a feature request is actually a bug report
A support ticket asking for a new setting can be a workaround for a bug in disguise. Getting the label wrong sends it to the wrong owner and queue.
Feedback loop5 min read
-
How to track feature requests without losing them
Feature request tracking usually fails one of two ways: nowhere, or somewhere nobody revisits. A system that survives both, and the labels worth using.
Feedback loop6 min read
-
Support tickets vs. feature requests: which do you trust?
A support ticket and a feature request board measure different things. Treating a spike in one as a spike in the other gives confident, wrong priorities.
Feedback loop5 min read
-
How to prioritize feature requests that keep piling up
A tracked backlog still leaves the hard question open: which request ships next. The frameworks worth using, where each breaks, and what vote counts hide.
Feedback loop5 min read
-
Closing the customer feedback loop from the changelog side
A feedback loop is closed when the person who asked is told it shipped. The loop in four steps, where it breaks, and why the changelog closes it.
Feedback loop8 min read
-
Feature request template that becomes a changelog entry
A feature request is only useful if it can be found when the thing ships. The template, the labels that route it, and the fields the changelog reads later.
Feedback loop6 min read
-
A public roadmap from your issue tracker, in three columns
A public roadmap is a promise about the future, so keep it small, drive it from the issues you already track, and move each item with a label on its issue.
Feedback loop6 min read
