How to Write Release Notes When the Feature Didn't Fully Ship
It is 2:00 PM on a release day, and you are staring at a blank document.
The deployment went out. The code is in production. But the marquee feature you were supposed to announce today is not really there. Maybe the phased rollout stalled at 10 percent. Maybe the backend API shipped, but the UI didn't make the cut. Or maybe the feature is technically live, hidden behind a flag that only three enterprise customers can actually toggle.
You have to publish release notes in the next few hours. You can't lie and say it is fully available. You can't say nothing, because you already told customers it was coming.
This is not a catastrophic failure. It is the normal state of modern software delivery. Partial releases are so common that a study of 32,425 GitHub release notes found that teams routinely document features in states of incompleteness, with no consistent standard for how to handle it. The problem is not that your feature half-shipped. The problem is that most teams have no plan for what to say when it does.
You write the release notes anyway. You just have to frame the reality of the codebase without drawing attention to the internal chaos that got you there.
Deciding If It Even Exists
The first problem is ontological. Does a feature exist if no one can see it?
The answer depends on where the code lives. If it is in production and any user could theoretically encounter it, you document it. A partial release is still a release. Martin Fowler's taxonomy of feature toggles is useful here: a "release toggle" is code that is deployed but not yet surfaced to users. The code exists. The feature, from a user's perspective, does not. These are different things, and your release notes need to reflect that distinction.
If the feature is flagged off for everyone except internal testers, it did not ship. Treat it as pre-release. Do not document it as available.
If the feature was pulled entirely at the last minute, do not pretend it shipped. But if you already announced it was coming in this version, you owe your users an update. You walk it back quietly. You focus on what did ship, then add a brief note about the delay: "We are still refining [Feature X], which will be available in a future update." Do not overpromise a new timeline unless you are certain you will hit it. Repeated delays erode trust in a way that a single honest "not yet" never does.
How to Frame the Half-State
When a feature exists in an awkward intermediate state, you need language that is accurate but not evasive. The goal is to communicate availability precisely, so users know what they can do and what is still coming, without sounding like you are hiding something.
The strategy changes depending on the feature's profile. If this was the headline item for the release, you have to address the gap directly. Users who were waiting for it will notice. A vague "improvements to data processing" does not cover for a missing dashboard that was featured in your roadmap announcement. Name what shipped, describe its current scope honestly, and say when the rest is coming — or say you do not know yet.
If the partial feature is one of twelve things in the update, a "beta" tag in the middle of the list is usually enough. Most users will not read that far.
When you have pre-announced a feature and it did not ship, the framing is different. You owe users a direct acknowledgment. The cleanest version is: lead with what did ship, then briefly note the delayed item. "We shipped [A], [B], and [C] in this release. [Feature X], which we announced for this version, has been moved to [Q3/a future release/when we have more to share]." That is it. No elaborate explanation. No apology tour. Users respect honesty about slippage far more than they respect the pretense that nothing slipped.
What Everyone Else Gets Wrong
The mistakes teams make in this scenario are entirely predictable.
They use vague language that makes users think they are missing something. "Improved data processing capabilities" means nothing. Users will spend twenty minutes looking for a button that does not exist, then file a support ticket.
They write release notes that imply full availability when the feature is actually gated. This is worse than saying nothing. It creates a specific expectation that the product then fails to meet, and the failure lands on support.
They overpromise the next release to compensate. "The full feature will be available next sprint" is a commitment you should not make unless you are completely certain. One broken promise is a mistake. Two in a row is a pattern.
They write two contradictory versions: one for internal teams explaining the actual state, and one for external users pretending everything is fine. The internal version always leaks. Or, more precisely, the confusion bleeds into every customer interaction your support and sales teams have for the next month. Internal and external release notes serve different audiences, but they cannot contradict each other. One version. Write it accurately. Distribute it everywhere.
Who Needs to Know Before You Hit Publish
Before these notes go live, you need internal alignment. This is not optional.
Support needs to know what to tell the customers who ask why they cannot access the new tool. They need a macro, or at minimum a clear one-sentence answer. If support finds out about the partial release from a customer ticket, you have already failed.
Sales needs to know which prospects can actually be shown the feature and which ones need to be told it is coming later. A sales rep who demos a feature that the prospect cannot access is a bad day for everyone.
Customer success needs talking points for the accounts that were specifically waiting for this release. These are the customers who will push back hardest if the notes do not match what they were promised.
You are not just publishing a document. You are setting the communication strategy for the entire company for the next two weeks. The release notes are the source of truth. Give your teams the checklist: what shipped, who has it, what the script is, and when to escalate.
The Debt You Just Created
When you publish release notes for a partial feature, you are taking out a loan.
You are committing to update those notes when the rest of the feature ships. This is documentation debt, and it compounds. Most teams write the initial "beta" release note and never circle back when the feature reaches general availability. The documentation drifts from reality. Users who search the changelog six months later find a "beta" tag on a feature that has been fully available for five months.
You have to track this obligation explicitly. The simplest version is a ticket in your backlog: "Update release notes for [Feature X] when it reaches GA." Someone has to own it.
This is where the mechanics of how you generate documentation start to matter. If your release notes are manually assembled by asking engineers what they did, you will always be fighting drift. Writing release notes from scratch for each release takes up to eight hours for an experienced developer. That time pressure is exactly why partial releases get documented imprecisely.
If your release notes are generated directly from pull requests and deployment events, they reflect what actually shipped. When the rest of the feature is merged, the system knows. Research on automated release note generation confirms that pull request-based approaches capture more than 54 percent of the changes teams actually ship, without requiring manual intervention to correct for scope changes.
Teams using Doc Holiday have a structural advantage here. The platform sources data from actual code commits, providing a foundation for documentation that is grounded in what deployed rather than what was planned. You still have to make the editorial judgment about whether to call it "beta" or "early access," and you still need to decide how much to say about what did not ship. The system provides the structure. The framing is still yours.
