Update versioning policy to treat utility/service API additions as no…

…n-breaking Co-authored-by: Patrik Oldsberg <[email protected]> Co-authored-by: Johan Haals <[email protected]> Signed-off-by: Fredrik Adelöw <[email protected]>
https-quantumblockchainai-atlassian-net · Nov 16, 2022 · cce755b · cce755b
1 parent 3a5aefb
commit cce755b
Show file tree

Hide file tree

Showing 2 changed files with 51 additions and 1 deletion.
diff --git a/REVIEWING.md b/REVIEWING.md
@@ -171,6 +171,37 @@ Exported types can be marked with either `@public`, `@alpha` or `@beta` release
 
 If a package does not have this configuration, then all exported types are considered stable, even if they are marked as `@alpha` or `@beta`.
 
+#### Changes that are not Considered Breaking
+
+There are a few exceptions that are not considered breaking in the [versioning policy](https://backstage.io/docs/overview/versioning-policy),
+primarily regarding Utility APIs and Backend Service interfaces (referred to "contracts" below) that are supplied by the
+Backstage core packages.
+
+Example of a non-breaking change to a contract which has a default
+implementation, since consumers typically only interact with that contract as
+callers of existing methods:
+
+```diff
+ export interface MyService {
+   oldMethod(): void;
++  newMethod(): void;
+ }
+```
+
+Changes such as these must still be marked with `**BREAKING PRODUCERS**:` in the
+changelog, to highlight them for those who might be implementing custom
+implementations of those contracts or putting mocks of the contract in tests.
+
+Example of a breaking change to a contract, which affects existing consumers and
+therefore makes it NOT fall under these exceptions:
+
+```diff
+ export interface MyService {
+-   oldMethod(): void;
++   oldMethod(): Promise<void>;
+ }
+```
+
 #### Type Contract Direction
 
 An important distinction to make when looking at changes to an API Report is the direction of the contract of a changed type, that is, whether it's used as input or output from the user's point of view. In the next two sections we'll dive into the different directions of a type contract, and how it affects whether a change is breaking or not.

diff --git a/docs/overview/versioning-policy.md b/docs/overview/versioning-policy.md
@@ -99,7 +99,7 @@ This versioning is completely decoupled from the Backstage release versioning,
 meaning you might for example have `@backstage/core-plugin-api` version `3.1.4`
 be part of the `1.12` Backstage release.
 
-Following versioning policy applies to all packages:
+The following versioning policy applies to all packages:
 
 - Breaking changes are noted in the changelog, and documentation is updated.
 - Breaking changes are prefixed with `**BREAKING**: ` in the changelog.
@@ -120,6 +120,25 @@ For packages at version `1.0.0` or above, the following policy also applies:
   changes without a deprecation period, but the changes must still adhere to
   semver.
 
+### Changes that are not Considered Breaking
+
+There are a few changes that would typically be considered breaking changes, but
+that we make exceptions for. This is both to be able to evolve the project more
+rapidly, also because the alternative ends up having a bigger impact on users.
+
+For all Utility APIs and Backend Services that _have_ a built-in implementation,
+we only consider the API stability for consumers of those interfaces. This means
+that it is not considered a breaking change to break the contract for producers
+of the interface.
+
+Changes that fall under the above rule, must be marked with
+`**BREAKING PRODUCERS**:` in the changelog.
+
+For any case of dependency injection, it is not considered a breaking change to
+add a dependency on a Utility API or Backend Service that is provided by the
+framework. This includes any dependency that is provided by the
+`@backstage/app-defaults` and `@backstage/backend-defaults` packages.
+
 ### Release Stages
 
 The release stages(`@alpha`, `@beta` `@public`) refers to the