**Last updated: September 30, 2023**

This document describes Firebase's policies for the following topics:

- [Introducing compatible changes, deprecations, and breaking changes](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#introducing-compatible-changes-deprecations-breaking-changes)

- [Communicating changes publicly](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#communicating-changes)

For specific details about versioning and maintenance, see the separate page
that contains Firebase's policies for
[versioning of versioned components](https://firebase.google.com/policies/changes-to-firebase/versioning-and-maintenance.md.txt).

<br />


*** ** * ** ***

<br />

## **Introducing compatible changes, deprecations, and breaking changes**

Firebase can make the following types of changes in its Firebase components:

- [Compatible changes](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#compatible-changes)

- [Deprecations](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#deprecations) (which include a deprecated phase)

- [Breaking changes](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#breaking-changes) (which could be decommission or
  end-of-maintenance events)

*** ** * ** ***

### Compatible changes

Compatible changes are events that do *not* require developers to do any work
when updating. For Firebase components, these changes include adding
deprecations, new features, and changes and bug fixes that are
backwards-compatible with our APIs and tooling.

For versioned components, Firebase introduces compatible changes in patch and
minor versions. Firebase ensures that patch and minor versions within a major
version are compatible, so developers can update safely.

*** ** * ** ***

### Deprecations

When a product or feature is marked as deprecated, it means that it is
obsolete. However, ***a deprecated product or feature is still available and
functional through the deprecated phase***.

Firebase strives to provide a replacement or alternative for products or
features that are deprecated.

Continued or future use of deprecated products and features is discouraged,
either because there is a preferred alternative or because there is an intention
to have a decommission or end-of-maintenance event in the future. A deprecation
is usually performed well in advance of the actual decommission or
end-of-maintenance event.

Deprecations are announced publicly according to our
[communication policy](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#communicating-changes). Firebase announces deprecations
for versioned components in minor or major versions. For unversioned components,
Firebase may announce deprecations at any time, although those tried to be
aligned within the versioned releases.

#### Understanding the deprecated phase

The deprecated phase is the time between the announcement of a product or
feature deprecation and its actual decommission or end-of-maintenance event.

- For deprecations of entire products, the deprecated phase will last at least
  12 months after the deprecation announcement.

- For deprecations within versioned components (like within SDKs), the
  deprecated phase will last at least until the next major release after the
  deprecation announcement (although there may be exceptions like critical
  vulnerabilities or breaking changes caused by dependencies).

  > [!NOTE]
  > **Example:** If an API is deprecated in v2.0.0, it may be removed in the v3.0.0 release. If an API is deprecated in v2.7.0, it may also be removed in the v3.0.0 release.

- If a breaking change is security- or abuse-related, due to regulatory
  requirements, or
  [other factors that cause breaking changes to Firebase](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#other-factors-that-cause-breaking-changes),
  then the deprecated phase can be quite short (even a matter of hours or
  days) to reduce the impact.

In the deprecation announcement, Firebase will provide the anticipated date
and/or version for the [decommission](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#decommissions) or
[end-of-maintenance (EoM)](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#end-of-maintenance) event. If there's a replacement
or alternative, Firebase will provide migration information in the announcement.
Then, during the deprecated phase, Firebase will work towards zero usage and/or
affected users before implementing the decommission or end-of-maintenance event.

*** ** * ** ***

### Breaking changes

A breaking change for a product or feature requires developers to do work,
because the state after the change is not backwards-compatible with the state
before it.

Breaking changes are preceded by a deprecation announcement and
[deprecated phase](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#deprecated-phase), and they are announced publicly according
to our [communication policy](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#communicating-changes). Firebase can make the
breaking change when the deprecated phase ends. For versioned components,
Firebase introduces breaking changes in major versions.

The two categories of breaking changes include the following event types:

- [Decommissions](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#decommissions)

- [End-of-maintenance (EoM)](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#end-of-maintenance)

#### Decommissions

Decommissioning is the act of removing a product or Firebase component so that
it's no longer accessible to developers. This makes decommissioning a breaking
change. Other terms commonly used for decommissioning include removal, turndown,
shutdown, sunset, discontinuation, and end-of-life.

#### End-of-Maintenance (EoM)

End-of-maintenance (EoM) indicates that a product or Firebase component (or
version of a component) is still available and functioning, but there will be no
further product development and no commitment to address any security issues,
bug fixes, or critical vulnerabilities. This makes EoM a breaking change, as it
means that developers will no longer receive updates or support for the product
or component.

> [!IMPORTANT]
> **Important:** Firebase officially only supports the latest major version of its versioned Firebase components. When we release a new major version, the older version enters the end-of-maintenance (EoM) phase. For example, when the Apple platforms SDK [v10.0.0](https://firebase.google.com/support/release-notes/ios.md.txt#version_1000_-_october_10_2022) was released, [v9](https://firebase.google.com/support/release-notes/ios.md.txt#version_950_-_august_23_2022) entered EoM.

#### Other factors that cause breaking changes in Firebase

Firebase SDKs depend on the platform providers (Google Cloud, Android, Apple,
Unity, etc.) and the associated ecosystem (languages, tools, and libraries). If
the platform provider causes breaking changes, Firebase SDKs must update
correspondingly to be in sync with the ecosystem. Firebase tooling, like the
Firebase CLI, also have dependencies on industry-standard tooling and
libraries, and they must update accordingly.

Updates can include breaking changes for other reasons, such as adding
stability, performance, and security improvements, adding idiomatic support for
languages, or applying current de-facto patterns and guidelines.  

Other major breaking changes, such as the removal of deprecated products or
services (not just specific APIs), can be caused by a variety of reasons. For
example, a new product may better meet the needs of developers, or products may
be integrated with other products to offer a better experience.

> [!NOTE]
> **Example:** If a new version of Android changes or removes an API that is used by the Firebase SDKs, we may need to update the Firebase SDKs to work with the new version of Android. Otherwise, apps using the Firebase SDKs may no longer work properly or as expected.

> [!NOTE]
> **Example:** Tooling changes on the Android platform, such as changes to Android Studio, can affect Firebase SDKs. For example, changes to the way that Android Studio manages dependencies can cause apps using Firebase SDKs to fail to compile or run. Additionally, changes to best practices for how apps are built and deployed can cause Firebase SDKs to fail to run or deploy on devices if the SDKs aren't updated accordingly.

<br />


*** ** * ** ***

<br />

## **Communicating changes publicly**

Firebase communicates changes to products and components in the following
ways:

- Sending emails to Firebase project Owners to notify them of
  deprecations and breaking changes (like decommissions and
  end-of-maintenance (EoM) events).

- Displaying banners and notifications in applicable developer interfaces,
  like the Firebase console, CLI, and documentation.

- Posting to the [Firebase "general" release notes](https://firebase.google.com/support/releases.md.txt).
  The Firebase SDKs and the Firebase CLI also have
  [SDK- or tool-specific release notes](https://firebase.google.com/support/releases.md.txt#latest-versions)
  with more details about each change.

For detailed information about the timelines for communicating a deprecation or
breaking change, see the applicable section in
[Introducing compatible changes, deprecations, and breaking changes](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#introducing-compatible-changes-deprecations-breaking-changes)
above. For details about the published information and resources typically
provided for each type of change, see
[Badging and information provided in release notes](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#release-notes).

### Badging and information provided in release notes

Every change in Firebase's release notes is badged according to the following
conventions for convenience; see the actual release notes and policies for
applicable details. This table also describes the published information and
resources typically provided for each type of change.

| **Badge** | **Description** | **Expected action by developer** | **Additional published information** |
|---|---|---|---|
| **Issue** | There is a known issue that developers should be aware of. | For versioned components, developers shouldn't update to this version if the issue could impact their app and there is no workaround. | Instructions or link to documentation about a workaround (if one exists). |
| **Fixed** | Firebase has fixed an issue. | For versioned components, developers should update to the new version to get the fix. | N/A |
| **Feature** | Firebase has added a new feature. | For versioned components, developers should update to the new version to access the new feature. Developers should follow instructions for any required actions to use the new feature. | As necessary, instructions or link to documentation about how to use the new feature. |
| **Changed** | Firebase has made a backwards-compatible change. | For versioned components, developers should update to the new version to get the change. Occasionally, changes require some kind of action to take advantage of the change, but these actions should be optional. | As necessary, instructions or link to documentation about how to take advantage of the change. For example, adding a new parameter to an existing class. |
| **Deprecated** | Firebase has marked a product or feature as deprecated. | Developers should plan to migrate to an alternative or stop using the product or feature before the communicated deprecated phase ends. **Note:** The product or feature is still available and functional through the [deprecated phase](https://firebase.google.com/policies/changes-to-firebase/introducing-and-communicating-changes.md.txt#deprecated-phase). However, continued or future use of deprecated products and features is discouraged, either because there is a preferred alternative or because there is an intention to have a decommission or end-of-maintenance (EoM) event in the future. | **1.** Instructions or link to documentation about migration to a replacement. <br /> **2.** The anticipated date and/or major version for the planned decommission or end-of-maintenance (EoM) event. This information will be provided in the email and release note announcing the deprecation. It's also usually found in the Firebase documentation or other applicable Firebase interface (for example, the Firebase console or CLI). |
| **Breaking Change** | Firebase made a breaking change. | For versioned components, developers should update to the new version to get the breaking change. To accommodate the breaking change, developers need to follow the published information about migration to a replacement. | Instructions or link to documentation about migration to a replacement. **Note:** This information about migration to a replacement was made available in the deprecation announcement at the beginning of the deprecated phase. |
| **Removed** | The product or feature is no longer available or functional. | For versioned components, developers should update to the new version. Developers should follow instructions for any required actions to accommodate the removal. | Instructions or link to documentation about migration to a replacement. **Note:** This information about migration to a replacement was made available in the deprecation announcement at the beginning of the deprecated phase. |