feat(docs): RFC to clarify _unstable naming convention for public APIs

[dmytrokirpa]

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:

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

Proposed Solution

Three coordinated changes:

1. Remove _unstable suffix from stable APIs

   • useBadge_unstable → useBadge
   • renderBadge_unstable → renderBadge
   • useBadgeStyles_unstable → useBadgeStyles

2. Maintain backward compatibility through deprecated re-exports

   export const useBadge_unstable = useBadge; // @deprecated

3. 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.

[github-actions]

📊 Bundle size report

✅ No changes found

[github-actions]

Pull request demo site: URL