API Deprecation

Introduction

This article is intended to guide you on the best practices regarding API deprecation. This includes both the process of deprecating an API as well as cleaning up already deprecated APIs.

Deprecating an API

The following are guidelines when you are considering deprecating an API.

Principles behind deprecating an API

When deprecating APIs, we must clearly communicate why the API is deprecated, what solution will replace it, and why these changes will ultimately benefit the user. As you are adding new functionality, or extending an existing one, strive towards API that is simple and consistent. When thinking of simplicity ask yourself if the change adds further interdependencies between API calls or need to contextually understand one API call to reason about another.

You should discuss the plan to deprecate and remove an API before committing the change. This should be done in the corresponding GitHub issues/PRs. If an API is marked as deprecated without a clear plan, then it can become difficult to cleanup in the future. Additionally, there are many cases where the additional discussion and planning will determine that the API should not have been deprecated in the first place.

Creating a GitHub Issue

When you deprecate an API, you should always create a GitHub issue to track the cleanup of the API. Use the "Deprecated API" template and fill in each of the categories listed in the template. Additionally, remember to assign the issue to whoever will own the cleanup of the API. If unsure, assign it to yourself.

The complexity and scope of an API will often determine the approach you may take when creating the corresponding GitHub issue. When an API is relatively simple and isolate, you may take a more tactical approach where the plan is clearly defined out. However, when handling a complex API with a larger scope, you may need a strategical approach, where more planning and discussion is required.

Examples

• Tactical approach for a simple API
• Strategic approach for a complex API

For reference, you can query all open GitHub issues related to API deprecation here.

Marking an API as deprecated in the codebase

The following is an example an API marked as deprecated. In this scenario, exampleString is made obsolete by exampleObject.getString(). This is communicated clearly in the comment. We also communicate when it was deprecated and when we expect to remove it. Additionally, we point to a GitHub issue in order to provide further explanation.

/**
 * @deprecated 1.0.0. This API will be removed in 2.0.0.
 * Use {@link exampleObject.getString} instead.
 * See {@link https://github.com/microsoft/FluidFramework/issues/ABCD} for context.
 */
public exampleString: string = "example";

For more details related to the @deprecated TSDoc tag, see here.

Cleaning up a deprecated API

To cleanup a deprecated API, your starting point should be the GitHub issue mentioned above. You should try to clarify any questions or concerns in the issue comments. Additionally, you should attempt to outline your solution in the GitHub issue and gather any necessary feedback before creating a PR.

Usage Considerations

When considering the removal of an API, you must first ensure all the occurrences of said API are removed. To do so, search both the FluidFramework and partner repositories. If occurrences are found, it is suggested to add phases to the GitHub issue outlining the work that must be done in order to fully remove the API.

Compatibility and Versioning

Whenever you make a change to an API, you need to consider the implications for packages which consumed that API. This will often lead to additional phases, such as creating a pre-release. For further guidelines, it is highly recommended to refer to this guide about compatibility and versioning to understand how to properly stage your changes in this scenario.

Communication

When removing an API, be sure to create a changeset with notes on the removed API. Changeset guidance can be found here and in the changeset FAQ. This should contain basic information about the removed API, which packages were affected, and the intended replacement is. You can also point back to relevant GitHub issues/PRs.

For larger conceptual changes, you may want to consider updating existing examples and documentation to help promote the updated coding patterns.