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

Deprecation Steps

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

2. Keep the tests using deprecated props named in a file with deprecated suffix, such as PersonaCoin.test.tsx -> PersonaCoin.deprecated.test.tsx.

3. Copy the test's snapshot output (or ensure it's the same if regenerated.)

4. Modify existing tests to use new prop.

   • Snapshot output should be identical in most cases, particularly if props naming is the only thing changing.

5. Add new property to interface.

6. 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.)

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

8. Move deprecated prop to end of interface, update comments with deprecation description and add @deprecated.

   tsxCopy

   /**
   * Primary text to display, usually the name of the person.
   * @deprecated Use 'text' instead.
   */
   primaryText?: string;
   

9. Make sure old and new tests pass.

10. Add call to warnDeprecations in constructor, like:

    tsxCopy

    constructor(props: IPersonaCoinProps) {
      super(props);
    
      // 'primaryText' is deprecated and 'text' should be used instead
      warnDeprecations('PersonaCoin', props, { 'primaryText': 'text' });
    }
    

11. warnDeprecations will most likely cause deprecated tests to fail. Override the warning callback as follows:

    tsxCopy

    // 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 ...
    });