Deprecation Guidelines
This guide outlines recommendations for deprecating API behavior, particularly related to component props.
An example PR following these steps can be found here: https://github.com/microsoft/fluentui/pull/4811
-
Ensure snapshot tests exist covering existing props functionality as a reference check against deprecation changes.
- The props you're deprecating should have representation in the snapshot output. Sometimes this may require getting the component under test into a certain state.
-
Keep the tests using deprecated props named in a file with deprecated suffix, such as
PersonaCoin.test.tsx
->PersonaCoin.deprecated.test.tsx
. -
Copy the test's snapshot output (or ensure it's the same if regenerated.)
-
Modify existing tests to use new prop.
- Snapshot output should be identical in most cases, particularly if props naming is the only thing changing.
-
Add new property to interface.
-
Optionally, temporarily comment out old prop to help find all uses throughout code base and change. (Some usage will be caught by the deprecation lint rule, but not in all cases.)
-
Update components that consume property as needed to support both deprecated and new props.
- Be sure to consider other components that both use and extend the modified interface. If a component needed a change, there's a good chance it will also need to continue supporting the deprecated prop and should also have deprecated tests.
-
Move deprecated prop to end of interface, update comments with deprecation description and add
@deprecated
./** * Primary text to display, usually the name of the person. * @deprecated Use 'text' instead. */ primaryText?: string;
-
Make sure old and new tests pass.
-
Add call to
warnDeprecations
in constructor, like:constructor(props: IPersonaCoinProps) { super(props); // 'primaryText' is deprecated and 'text' should be used instead warnDeprecations('PersonaCoin', props, { 'primaryText': 'text' }); }
-
warnDeprecations will most likely cause deprecated tests to fail. Override the warning callback as follows:
// or @fluentui/utilities in 8+ import { setWarningCallback } from '@uifabric/utilities'; describe('PersonaCoint', () => { beforeAll(() => { // Prevent warn deprecations from failing test const noOp = () => undefined; setWarningCallback(noOp); }); afterAll(() => { setWarningCallback(); }); // tests ... });
- FAQ - Fabric and Stardust to Fluent UI
-
@fluentui/react
Version 9 -
@fluentui/react
Version 8 - Contributing to the
7.0
branch - How to apply themes (version 7/8)
- Planning and development process (for work by the core team)
- Conducting meetings Style guide
- Keeping up with review requests
- RFC review process
- Setup (configuring your environment)
- Fluent UI React version 7/8
- CLA
- Overview
- Repo structure
- Development process
- Contributing to previous versions
- API Extractor
- Build command changes made in early 2020
- Component implementation guide
- Creating a component
- Implementation Best Practices
- Theming
- Documenting
- Styling (old approach)
- Overview
- Testing with Jest
- E2E testing (Cypress)
- Visual testing (Screener)
- Accessibility review checklist