How to Write Release Notes for Gradual Feature Rollouts

The code is in production. The pull request is merged. The feature flag is flipped to exactly five percent of your user base.

Now you have to write the release notes.

This is where the documentation breaks down. You have a feature that exists, but only for a fraction of the people reading your changelog. If you announce it broadly, ninety-five percent of your users will log in, look for the feature, fail to find it, and submit a support ticket asking if their account is broken. If you say nothing, the five percent who do have the feature will wonder what just changed in their workflow without any explanation.

The answer is to publish the release notes immediately when the rollout begins, but frame the language entirely around the state of the deployment rather than the state of the feature. You do not announce that the feature is live. You announce that the rollout has started.

The Trap of the Silent Rollout

The instinct of most product teams is to wait. They want to hold the release notes until the feature hits one hundred percent availability.

This is a mistake.

Gradual rollouts, canary releases, and phased deployments are designed to mitigate risk by exposing a small cohort of users to new code before a wider release. But if you do not document the change for that initial cohort, you are not mitigating risk. You are just confusing a smaller number of people.

The distinction between deployment and release matters here. When a feature flag controls access, the code is deployed to production but not released to all users — a distinction at the heart of progressive delivery. Your changelog needs to reflect that distinction. A note that says "this feature is now available" is accurate for the five percent. It is actively misleading for the ninety-five percent.

The changelog is not a marketing announcement. It is an operational ledger. It needs to reflect reality, even when reality is fragmented.

The timing question is easier than it sounds. Publish when the rollout starts. Not when it hits fifty percent. Not when it hits one hundred. The moment the first user has access to the new behavior, the changelog is out of date if it says nothing. Keep a Changelog puts the principle simply: there should be an entry for every state change.

The Vocabulary of Partial Reality

The language you use to describe a phased rollout determines whether you generate excitement or support tickets.

Do not use the phrase "now available." That implies universal access. Do not use "coming soon." That implies the code has not shipped. Both are technically wrong for a feature that is live for some users and invisible to others.

Use active, progressive verbs. "We are rolling out." "Beginning to deploy." "Starting a phased release to Enterprise accounts."

When GitHub updated the format of their App installation tokens, they did not announce the change as complete. They announced a staged rollout with explicit timelines: "Starting April 27th 2026 and over the coming weeks, we will begin a staged rollout." The language was operational, not promotional.

Google Workspace defines rollout pace explicitly in every feature update. A representative entry reads: "Rapid Release domains: A gradual rollout (up to 15 days for feature visibility)." They also give admins a choice of release tracks, so users can understand exactly why their colleague has a feature they don't.

Microsoft uses three explicit status labels in its Message Center: "Scheduled," "Rolling out," and "Launched." Each label maps to a real state of the deployment. The user does not have to guess.

The goal is to give the reader enough context to self-identify whether they should have access. If they know the rules of the rollout, they will not submit a ticket when the feature is missing.

Here is a before-and-after that illustrates the difference:

Before (vague): "We've added a new dashboard view for analytics."

After (clear): "We're rolling out a new analytics dashboard view to all accounts over the next two weeks. Enterprise accounts will see it first, starting today. All other accounts will have access by [date]. If you don't see it yet, no action is needed."

The "before" version generates support tickets. The "after" version answers the support ticket before it is written.

What Happens When You Pause

Sometimes the canary dies.

The rollout hits ten percent, the error rates spike, and you have to halt the deployment. Or worse, you have to roll it back entirely. One of the core benefits of canary releases is the ability to reroute users back to the old version instantly if problems appear. The rollback is a feature of the deployment strategy. But it is also a documentation event.

You have to communicate the pause.

When GitHub paused new trials for Copilot Pro due to abuse, they updated their changelog immediately: "All GitHub Copilot Pro trials, including existing trials, have been paused while our investigation continues." They did not delete the original announcement. They did not pretend the feature never existed. They appended the pause to the public record.

The same principle applies to rollbacks. A rollback is a change in system state. The changelog documents changes in system state. The rollback belongs in the changelog.

If you do not document the reversal, the users who had the feature and lost it will think they broke something. The support tickets that follow a silent rollback are worse than the ones that follow a bad release note.

A paused rollout note does not need to be alarming. "We've temporarily paused the rollout of [feature] while we investigate a performance issue. We'll share an update when the rollout resumes." That is enough. It is honest. It sets an expectation. It prevents the worst-case interpretation.

The Support Deflection Layer

The ultimate test of a phased rollout release note is whether it deflects support tickets.

A good release note answers three questions before the user can ask them: What is this? Do I have it? If I don't have it, when will I get it?

Stripe handles this by maintaining a distinct public preview release channel, explicitly stating that preview features use different API versions and may be subject to breaking changes. The boundary between what is fully available and what is in phased deployment is clearly drawn. Users know exactly what they are opting into.

Feature flags add a layer of complexity that most documentation workflows are not built for. The feature toggle patterns described by Pete Hodgson separate the concept of deployment (code is in production) from release (code is available to users). A release note written at deployment time is accurate. A release note written at the time of full release is also accurate. The problem is the gap between them, when the feature exists in a state that is neither fully deployed nor fully released.

Keeping a changelog accurate when the state of a feature is time-dependent requires someone to remember to update the note when the rollout hits fifty percent, and again when it hits one hundred. In practice, that update rarely happens. The documentation drifts from the deployment reality. The changelog says "rolling out" six months after the feature reached everyone.

This is the operational problem Doc Holiday is designed to address. It generates release notes that pull rollout percentage and availability criteria directly from feature flags or deployment metadata, and when the flag state changes, the system surfaces that change to your team so engineers can review and validate the documentation before it goes out. The release note stays tethered to the actual state of the rollout, without requiring anyone to manually track which cohort has access to which feature on any given Tuesday.