Firebase's policies for introducing changes and communicating those changes

Last updated: September 30, 2023

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

For specific details about versioning and maintenance, see the separate page that contains Firebase's policies for versioning of versioned components .


Introducing compatible changes, deprecations, and breaking changes

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

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 . 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).

  • If a breaking change is security- or abuse-related, due to regulatory requirements, or other factors that cause breaking changes to Firebase , 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 or end-of-maintenance (EoM) 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 , and they are announced publicly according to our communication policy . 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

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.

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.


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 . The Firebase SDKs and the Firebase CLI also have SDK- or tool-specific release notes 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 above. For details about the published information and resources typically provided for each type of change, see Badging and information provided in 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 . 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.

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.