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. This must be done in the codebase with supporting context in GitHub issues/PRs.

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. Below are items which every GitHub issue should have.

1. The "api deprecation" label
2. Somebody assigned to the issue
3. Context for why it was deprecated
4. An explanation about the intended replacement/solution, and a plan to complete achieve it.
5. An expected timeline for when the cleanup will be completed. If possible, a specific release number.
6. Indications if there are any dependencies in the FluidFramework repository
7. Clearly layout phases to complete the cleanup

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. Additionally, we point to a GitHub PR/issue in order to provide further explanation.

/**
 * @deprecated This API will be removed in a future release. 
 * Use `exampleObject.getString()` instead. See #1234 for more context.
 */
public exampleString: string = "example";

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.

Staging Changes

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.