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 an API, 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, there is a string property that is made obsolete a function which can access the same string using the underlying object. 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 intended replacement/solution
5. Indications if there are any dependencies in the FluidFramework or partner repos
6. If necessary, 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 in a package below the client layer (i.e. @fluidframework/driver-definitions), 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.