feat(docs): RFC to clarify `_unstable` naming convention for public APIs by dmytrokirpa · Pull Request #35694 · microsoft/fluentui

dmytrokirpa · 2026-01-22T14:22:45Z

Summary

This RFC proposes deprecating and renaming all public API exports with the _unstable suffix in stable Fluent UI React v9 packages. The current naming convention creates confusion about API stability guarantees and blocks the introduction of truly experimental features.

Problem Statement

Currently, ~62 packages export ~1,300+ APIs with the _unstable suffix (e.g., useBadge_unstable, renderBadge_unstable). Despite the naming suggesting volatility, these APIs are:

Fully documented and supported
Subject to standard semantic versioning
Used in production environments
Treated as stable public APIs

This creates three main issues:

Misleading naming: The suffix suggests APIs might change at any time, contradicting their actual stability guarantees
Blocked innovation: No clear naming convention for truly experimental features that can change/be removed without notice
Documentation confusion: Requires constantly explaining that _unstable doesn't actually mean unstable

Proposed Solution

Three coordinated changes:

Remove _unstable suffix from stable APIs
- useBadge_unstable → useBadge
- renderBadge_unstable → renderBadge
- useBadgeStyles_unstable → useBadgeStyles

Maintain backward compatibility through deprecated re-exports

export const useBadge_unstable = useBadge; // @deprecated

Reserve UNSTABLE_ prefix (all caps) exclusively for experimental features

export const UNSTABLE_useExperimentalFeature = () => {
  /* ... */
};

Migration Support

Automated codemod: npx @fluentui/codemods v9-remove-unstable-suffix
Deprecation warnings in current release
Breaking change only in next major version
Clear documentation and partner outreach

Timeline

Feedback period: Through 2026-02-15
Implementation: v9.x release (2026-03 to 2026-04)
Migration period: v9.x through next major release
Cleanup: Remove deprecated exports in next major version

Is this a breaking change?

No - deprecated re-exports maintain full backward compatibility. The removal of deprecated exports in the next major release will be a breaking change following standard major version semantics.

Related Issue(s)

This RFC addresses long-standing confusion around API stability and enables clearer communication about experimental features.

…r public APIs

github-actions · 2026-01-22T14:25:48Z

📊 Bundle size report

✅ No changes found

github-actions · 2026-01-22T14:26:10Z

Pull request demo site: URL

docs/react-v9/contributing/rfcs/react-components/convergence/unstable-naming-convention.md

Hotell

Left comments/questions.

we should probably split this into 2 RFCs to proceed faster

1 - removing/deprecating _unstable which we have probably agreement to proceed
2 - experimntal API approach

Hotell · 2026-02-03T16:20:41Z

docs/react-v9/contributing/rfcs/react-components/convergence/unstable-naming-convention.md

+- **RFC Approval & Feedback**: 3 weeks (deadline: 2026-02-15)
+
+  - Gather core maintainer consensus on approach
+  - Finalize codemod RFC in parallel


we probably dont need to proceed with this change with the codemod as dependency

one negative aspect of immediate enablement via "automating" the switch to different symbols would force whole chain of pressure on all teams needing to bump to latest fluent in order to not break runtime.

We're not going to force anyone switch over. Folks can choose to move to the new APIs if they want to avoid using deprecated APIs, but the old ones will still be available, so nothing will break at runtime.

what I meant:

Scenario 1 🚨:

there is lib-A/sub-app-A that bumps to latest and applies codemod

there is lib-B/app-B` that uses A, but it's on older version of fluent,

A runs the codemod and ships new version

B is forced to be on the same version ( which should happen eventually ) but if that is not synced -> they would have runtime issue/broken app.

Scenario 2 ✅:

Fluent is part of sandbox env exposing API for devs to provide custom code.

once the sandbox applies codemod all users will all good if sandbox doesn't expose fluent apis in an explicit way where the transform could break the contract

I'm not sure I understand what you mean, but if we're talking about renaming useX_unstable to useX via codemod, then both apps should be fine, as it's a alias to the same thing/reference, and we're keeping both exports - so there shouldn't be any runtime errors.

yes that works,

i meant this scenario:

// sandbox api / lib / app A export {useX_unstable } from '@fluentui/react-components' // ⬇️ export {useX } from '@fluentui/react-components'

// user code in sandbox / lib / app B // 🚨 import {useX_unstable} from '@org/ui'

yes that works,

i meant this scenario:

// sandbox api / lib / app A export {useX_unstable } from '@fluentui/react-components' // ⬇️ export {useX } from '@fluentui/react-components'

// user code in sandbox / lib / app B // 🚨 import {useX_unstable} from '@org/ui'

Are you talking about breaking changes caused by the codemod? I think that's on whoever runs the codemod, not the codemod itself, since it just did its job and moved things away from deprecated APIs.

Hotell · 2026-02-03T16:30:45Z

docs/react-v9/contributing/rfcs/react-components/convergence/unstable-naming-convention.md

+
+Provide automated codemod to help consumers migrate with minimal manual effort:
+
+- **Command**: `npx @fluentui/codemods v9-remove-unstable-suffix`


out of scope for this PR but here is the gist how I envision our tools (because codemod package is already taken for v8 related things):

we ship @fluentui/cli which would have various sub-commands for various things we might need as we progress

migrate

migration defined in json file ( similar approach as nx )
@fluentui/cli migrate --run-migrations=migrations.json

invoking particular migration directly
@fluentui/cli migrate remove-unstable-suffix

report

@fluentui/cli report

Node : 22.21.1 OS : darwin-arm64 Native Target : aarch64-macos npm : 10.9.4 @fluentui/react-components : 9.0.1 @fluentui-contrib/foo-bar : 0.11.2

stats

scans codebase path and generates report for usages of all fluent apis ( imports, props, etc )
@fluentui/cli stats <path>

agent

setups Skills, mcp etc

@fluentui/cli agent init

Hotell · 2026-02-03T16:35:05Z

docs/react-v9/contributing/rfcs/react-components/convergence/unstable-naming-convention.md

+
+1. Remove the `_unstable` suffix from stable APIs
+2. Maintain backward compatibility through deprecated re-exports
+3. Reserve `UNSTABLE_` prefix exclusively for experimental features


suffix:

to avoid "confusion" we should probably go with EXPERIMENTAL_ prefix

experimental api exposure

while exposing these directly from existing packages is convenient for both maintainers and consumers it might generate side effects causing issues with bundling and tree shaking in user land. for these reason it might be probably best to expose /experimental api endpoints

experimental api removal/change

to not break users we will need to keep this in for 1-2 major version minimum and we cannot change those APIs as well as they are part of STABLE packages. with this in mind besides having a "prefix" to denote to user that this is experimental it acts as stable from semver POV

suffix:

to avoid "confusion" we should probably go with EXPERIMENTAL_ prefix
experimental api exposure

while exposing these directly from existing packages is convenient for both maintainers and consumers it might generate side effects causing issues with bundling and tree shaking in user land. for these reason it might be probably best to expose /experimental api endpoints

I'm fine with both suggestions of going with EXPERIMENTAL_ prefix and /experimental entry-points for packages

experimental api removal/change

to not break users we will need to keep this in for 1-2 major version minimum and we cannot change those APIs as well as they are part of STABLE packages. with this in mind besides having a "prefix" to denote to user that this is experimental it acts as stable from semver POV

The whole point was to allow having experimental APIs that could be changed/removed and not considering them a part of public contract until they finalized/moved to stable. If we can't establish this convention for some reason then there is no point of introducing this pattern, we just might only need to do clean up and that's it

Hotell · 2026-02-03T16:41:17Z

docs/react-v9/contributing/rfcs/react-components/convergence/unstable-naming-convention.md

+/**
+ * @deprecated Use `useBadge` instead. Will be removed in the next major release.
+ */
+export const useBadge_unstable = useBadge;


curious what's the opinion about doubling our API surface because of this change

agree that's not ideal scenario, but we need it to make sure everything stays backward compatible

Hotell · 2026-02-03T16:42:40Z

docs/react-v9/contributing/rfcs/react-components/convergence/unstable-naming-convention.md

+
+**Criteria for `UNSTABLE_` prefix:**
+
+- Explicitly documented as experimental


we will probably go with @experimental jsdoc annotation right ?

Hotell · 2026-02-03T16:45:09Z

docs/react-v9/contributing/rfcs/react-components/convergence/unstable-naming-convention.md

+**For stable packages (v9 and later):**
+
+- All stable APIs have clean names without instability markers
+- Internal APIs shouldn't be exported; use `@internal` JSDoc tag for documentation


seems like good time to open again lint rule implementation for no-annotate.

we could also approach this the other way around -> only @public annotated apis can be exported

this can be checked already by api extractor and simple failing tool could be written to check this

question is how to properly decouple experimental things to not be used "by accident" in stable apis, which would probably trigger chain of issues when "removing" these experimental ones in next major

feat(docs): introduce RFC to clarify _unstable naming convention fo…

18847a5

…r public APIs

github-actions bot added the Type: RFC Request for Feedback label Jan 22, 2026

dmytrokirpa changed the title ~~feat(docs): introduce RFC to clarify _unstable naming convention for public APIs~~ feat(docs): RFC to clarify _unstable naming convention for public APIs Jan 22, 2026

dmytrokirpa self-assigned this Jan 27, 2026

Merge branch 'master' into docs/deprecate-unstable-rfc

7bb065d

dmytrokirpa marked this pull request as ready for review January 27, 2026 14:20

dmytrokirpa requested review from a team as code owners January 27, 2026 14:20

CampbellOwen reviewed Jan 28, 2026

View reviewed changes

docs/react-v9/contributing/rfcs/react-components/convergence/unstable-naming-convention.md Show resolved Hide resolved

dmytrokirpa requested a review from CampbellOwen January 30, 2026 10:45

CampbellOwen approved these changes Jan 31, 2026

View reviewed changes

tudorpopams requested a review from layershifter February 3, 2026 13:04

dmytrokirpa requested a review from Hotell February 3, 2026 13:53

Hotell reviewed Feb 3, 2026

View reviewed changes


		Provide automated codemod to help consumers migrate with minimal manual effort:

		- Command: `npx @fluentui/codemods v9-remove-unstable-suffix`


		Criteria for `UNSTABLE_` prefix:

		- Explicitly documented as experimental

Conversation

dmytrokirpa commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Problem Statement

Proposed Solution

Three coordinated changes:

Migration Support

Timeline

Is this a breaking change?

Related Issue(s)

Uh oh!

github-actions bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Bundle size report

Uh oh!

github-actions bot commented Jan 22, 2026

Uh oh!

Uh oh!

Hotell left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Hotell Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

migrate

report

stats

agent

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dmytrokirpa commented Jan 22, 2026 •

edited

Loading

github-actions bot commented Jan 22, 2026 •

edited

Loading

Hotell Feb 6, 2026 •

edited

Loading

`migrate`

`report`

`stats`

`agent`