Feature flag retirement: remove the old behavior safely

Decision requested: retire the release flag without reviving the old path

A feature reaching full rollout does not make its flag safe to delete. Deployed code may still evaluate the flag, and an older client may use a fallback that selects the previous behavior when the flag disappears. Retirement needs evidence about those consumers as well as agreement that the new behavior should remain.

This proposed decision memo concerns a temporary release flag for a new account-settings flow. The team wants to make that flow permanent and remove the old branch. It does not cover a permanent operational kill switch or a flag that still represents an active product entitlement. Those controls need their own continuing ownership and lifecycle.

The downloadable retirement packet and consumer matrix are proposed planning artifacts. They have five consumer cohorts and unfilled evidence fields. No flag platform, deployed client or retirement rollout was tested for this article.

Product position: the chosen behavior must survive configuration removal

The product decision is to keep the new settings flow for every supported cohort. Engineering must translate that decision into code that no longer depends on the temporary flag. Deleting a control-plane entry while leaving its evaluations in place is a different change: it may cause callers to take a configured or SDK-level default.

Unleash's guidance for managing flags in code describes removing flag references and deploying the updated code before retiring the flag configuration. Its feature-flag concepts distinguish flag lifecycle concerns from simply changing an enabled state. Check the actual provider's behavior for a missing, archived or unavailable flag; those conditions need not be interchangeable.

The memo's proposed acceptance criterion is specific: supported clients continue to use the selected settings behavior after temporary configuration is removed. It does not accept "the flag no longer appears in the dashboard" as proof. The dashboard reflects configuration state, while customers execute deployed code.

Before approving retirement, product and engineering should also decide whether the old behavior remains a valid rollback target. If data or dependent workflows have changed, flipping a flag back may no longer be a complete rollback. The canary rollback-gate article shows why a rollback decision needs evidence about the state it will restore.

Engineering evidence: enumerate the consumers that can still evaluate it

The proposed matrix covers current servers, servers in a rolling deployment, cached browser bundles, supported mobile versions and background workers. Each row asks for the flag reference, chosen fallback and evidence that the replacement code is active. The categories are a starting inventory, not a claim that every SaaS product has exactly those five populations.

A source search in the current branch is useful but incomplete. It can establish that this checkout has no remaining reference. It cannot establish that every browser tab refreshed or every supported mobile installation updated. Keep the repository result and the deployed-consumer result as separate evidence fields.

Evaluation telemetry can help locate active references when the provider and SDK expose it. An interval with no observed evaluations does not prove a dormant client no longer exists. State the coverage and observation window, then combine it with the supported-client inventory. Do not replace unknown cohorts with an assumed zero.

Release sequence: remove the dependency before removing its configuration

The proposed sequence begins with a code change that makes the selected behavior unconditional for the intended consumers and removes the obsolete branch. Tests should cover that chosen behavior directly. A test suite that only mocks the flag as enabled can continue to depend on the flag abstraction without proving it is safe to retire.

Deploy the change through the application's normal release controls and inspect the cohorts in the matrix. For long-lived clients, the team may need to keep configuration available while supported old versions remain. Another supported strategy may explicitly change their fallback behavior or retire those versions under the product's existing compatibility policy. Choose based on actual client capabilities rather than an arbitrary waiting period.

Only after the required consumers no longer depend on the flag should the team remove or archive its configuration using the provider's lifecycle process. Keep the exact flag key and retirement decision in an internal record so a future engineer does not casually reuse the key for unrelated behavior while an old client still knows it.

The API deprecation article also tracks consumer migration, but flag retirement has an additional failure mode: a missing evaluation can select a default branch without producing an obvious HTTP error. The acceptance test must inspect the resulting behavior, not only request success.

Rollback position: an old build is another flag consumer

A release may appear fully migrated until an operator deploys the previous server image. If that image still evaluates the deleted flag, the rollback can reintroduce the old fallback. Review rollback artifacts alongside currently running versions, including worker images that an automated recovery process can restart.

The decision packet asks whether rollback means restoring old code, reverting a configuration or deploying a forward fix. Each option has prerequisites. Recreating a flag with its old name may not recreate targeting, cached values or the state of every client. Do not treat that action as a universal repair after deletion.

The proposed acceptance sheet includes configuration absence, provider unavailability, an old rollback build and a dormant worker. These are distinct tests. A missing flag and an unavailable provider may trigger different behavior, even if both happen to select the same default in one SDK setup.

Approval evidence: close the unknowns or retain the dependency

The retirement owner should present the chosen permanent behavior, consumer evidence and rollback decision together. A cohort marked unknown requires an explicit product and engineering disposition. Leaving configuration in place while resolving that cohort may be the correct outcome; it is not evidence that the release itself failed.

Record which tests ran, which versions they covered and what remains unsupported. The memo does not supply a universal number of quiet days after which deletion becomes safe. A rarely used client can outlive a short observation window, and a fast-moving server fleet may become evaluation-free much sooner.

Completion means the temporary dependency has been removed under the declared support policy and the chosen behavior continues without it. The packet makes that claim reviewable. Until its pending evidence is filled by the actual system, it remains a retirement proposal.

Sources

Documentation checked September 6, 2026.

1. Unleash: manage feature flags in code
2. Unleash: feature flag lifecycle