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

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.

Once a plan is solidified, 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.

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";

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 the 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 or partner repos
7. Clearly layout phases to complete the cleanup

For reference, see an example issue. Additionally, you can query all open GitHub issues related to API deprecation 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. Additonally, 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.