OSS Library Breaking Change Policy

Objective

This document describes a policy for deprecating and removing functionality in Google's Generally Available (GA) open-source libraries that have versioned releases. This policy is not applicable to major OSS projects like Chromium or Android, which all have their own communities and policies. This policy also does not apply to server-side APIs, including the Cloud service APIs. Information about the Cloud service API policy is available at https://cloud.google.com/apis/docs/resources/enterprise-apis.

Breaking Change

A breaking change is a change to supported functionality between released versions of a library that would require a customer to do work in order to upgrade to the newer version. It is advised that library owners (or "language leads") document for customers what constitutes approved and supported usage of their libraries.

Policy

1. All breaking changes require a major version bump

   A release containing one or more breaking changes to a Generally Available API must bump its major version number to indicate to users and package managers that there are incompatibilities that may break them. All breaking changes should be clearly documented in the release notes, along with instructions for how users should update their code. Users will then know that there's risk with upgrading to the new version, and may do so at their own convenience.

   Dropping support for a language standard or runtime may also be an example of a breaking change, depending on the established support guarantees of the library. Additionally, in languages that do not have dependency-aware package managers (e.g., C++), the addition of a new dependency may also be a breaking change if it requires the customer to do explicit work to satisfy the dependency. Alternatively, dropping support for a platform that itself is outside of vendor support may not be considered a breaking change.

2. The highest version number is always supported

   A release must remain supported until it is superseded by a subsequent release, or the whole repo is clearly deprecated and documented as unsupported. Support can be stopped immediately if the newer release shares the same major version number (i.e., there are no breaking changes when upgrading to the newest release that shares the same major version). If the newest release has a higher major version number, support can be phased out as described next since upgrading may result in a breaking change for the user.

3. The newest release for non-highest major versions receives 12-months of support

   When a release is superseded by a release with a higher major version number, the previous release will be supported for at least 12-months after the new release is made and maintains its existing bug/issue SLO for customers. This will give customers time to upgrade and deal with any breakages that may result. Patch releases within non-highest major versions supersede prior releases and remain supported for the remainder of the 12 months. Non-patch releases that introduce new functionality (i.e., minor version bumps in semver parlance) in non-highest major versions supersede prior releases and restart the support window.

   This support guarantee ensures that customers can continue using the previous release with confidence that any bugs they file will be responded to as if the bugs were reported against the newest release. This support requirement does not specifically require teams to automatically back/forward port fixes between the current and older releases, though teams may decide to do so¹.

Example

The following diagram shows the support windows for releases of the hypothetical "Foo" 1.x and 2.x release lines.

Note that it's up to the library owner whether they want to actively support multiple branches, as the policy presented in this document would allow. However, it is expected that a more common approach would be phase out support for a major version when a higher major version is released.

It is advised at the top of this document to avoid multiple major version bumps per year. However, if a team deems it necessary to do so, the team must pay the cost of supporting all previous releases for the full duration of their required 12-month support window. For example, the following diagram shows what would happen if "Foo 2.0" and "Foo 3.0" were both released a couple months apart. In this example, starting in November the team would be responsible for supporting all three of Foo 3.0 (current), Foo 2.0 (until Nov of the following year), and Foo 1.1 (until Aug of the following year).

Notes