paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 37 Packages Projects Releases Wiki Activity

Update versioning policy to treat utility/service API additions as non-breaking

Browse Source 
Co-authored-by: Patrik Oldsberg <poldsberg@gmail.com>
Co-authored-by: Johan Haals <johan.haals@gmail.com>
Signed-off-by: Fredrik Adelöw <freben@gmail.com>
This commit is contained in:
Fredrik Adelöw
2022-11-16 12:10:15 +01:00
parent 3a5aefb4f8
commit cce755b5af
2 changed files with 51 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
REVIEWING.md
+31
View File
@@ -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.
docs/overview/versioning-policy.md
+20 -1
View File
@@ -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