From 0970820ed04969428971e70716467fc655176007 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 22 Dec 2021 11:30:58 +0100 Subject: [PATCH 1/6] docs: add initial versioning policy doc Co-authored-by: Johan Haals Signed-off-by: Patrik Oldsberg --- docs/overview/versioning-policy.md | 158 +++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 docs/overview/versioning-policy.md diff --git a/docs/overview/versioning-policy.md b/docs/overview/versioning-policy.md new file mode 100644 index 0000000000..64f4601ed4 --- /dev/null +++ b/docs/overview/versioning-policy.md @@ -0,0 +1,158 @@ +--- +id: versioning-policy +title: Versioning Policy +description: +--- + +## The Purpose + +- Release cadence and naming 1.0, 1.1, 1.2, etc. + - does not map to semver + - Backstage 1.2 is a manifest of multiple versions of packages. +- X need to be greater then Y or there will be dragons +- X is supported for N versions + +## Backstage releases + +A Backstage release is a manifest of several packages and plugins that work well +together. The overarching version of this manifest is decoupled from the +individual package versions. + +There are two different release lines, each with their own versioning policy and +release cadence. The first one is the main release line, which provides +regularly scheduled and releases with high stability. On top of that there is a +Next release line which provides early access to changes in the upcoming main +release. + +## Release Lines + +### Main Release Line + +Release cadence: Once every 2 months + +The main release line in versioned with a major and minor version and does not +adhere to [semver](https://semver.org). + +The major release if there ever is one, will denote a significant improvement or +change to the Backstage platform. It may come with a large new set of features, +or a switch in the product direction, but other than that it is not different +than a minor release. + +Minor releases are the most common type of release and the one that is used by +default. Each new minor version can contain new functionality, breaking changes, +and bug fixes. + +Both major and minor releases are governed by the +[versioning policy](#versioning-policy) in the same way, both of them being +treated as one incremental release. + +### Next Release Line + +Release cadence: Weekly + +The next release is a weekly snapshot of the project. This is the quickest way +to get access to new functionality in Backstage but there is no guarantees +around breaking changes in these releases. + +## Package versioning + +Every individual package is versioned according to [semver](https://semver.org). +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. + +## Versioning policy + +The following versioning policy applies to the main release line. The next +release line provides no guarantees. + +The versioning policy applies to all packages that are part of the main release +line, i.e. on version 1.0 or above. + +- Each release may contain breaking changes, but they will only be done when + necessary and with as low impact as possible. When possible, there will always + be a deprecation path for a breaking change. +- Breaking changes are introduced with a clear upgrade path. +- Deprecations are valid for the duration of a single release, after which they + may be completely removed. +- Security fixes **may** be backported to older releases based on the simplicity + of the upgrade path and severity of the vulnerability. +- We promise to do our best to adhere to this policy. + +The purpose of the Backstage Stability Index is to communicate the stability of +various parts of the project. It is tracked using a scoring system where a +higher score indicates a higher level of stability and is a commitment to +smoother transitions between breaking changes. Importantly, the Stability Index +does not supersede [semver](https://semver.org/), meaning we will still adhere +to semver and only do breaking changes in minor releases as long as we are on +`0.x`. + +Each package or section is assigned a stability score between 0 and 3, with each +point building on top of the previous one: + +- **0** - Breaking changes are noted in the changelog, and documentation is + updated. +- **1** - The changelog entry includes a clearly documented upgrade path, + providing guidance for how to migrate previous usage patterns to the new + version. +- **2** - Breaking changes always include a deprecation phase where both the old + and the new APIs can be used in parallel. This deprecation must have been + released for at least two weeks before the deprecated API is removed in a + minor version bump. +- **3** - The time limit for the deprecation is 3 months instead of two weeks. + +## Release Timeline Example + +- 2022-02-01: 1.0 + + - core-app-api@1.0.2 + - core-plugin-api@1.0.1 + + .. core-app-api@1.0.2-next.0 .. core-app-api@1.0.2-next.1 .. + core-app-api@1.0.2-next.2 .. core-app-api@1.0.2-next.3 + +- 2022-04-01: 1.1 + + - core-app-api@1.1.0 + - core-plugin-api@1.0.1 + + .. core-app-api@1.1.0-next.0 .. core-app-api@1.1.0-next.1 + + .. core-app-api@1.1.1 <- security fix release NOTE: not based on the existing + master, but on 1.1.0 TEST THIS, how does it interact with the `next` release + line? + + .. core-app-api@1.1.1-next.2 <- does this move up to 1.1.1 after the security + release? .. core-app-api@1.1.1-next.3 + +- 2022-06-01: 1.2 + - core-app-api@1.1.2 + - core-plugin-api@1.0.1 + +## Individual Package Policy + +In order for Backstage to function properly the following versioning rules must +be followed. + +- If the `@backstage/app-defaults` package is used, it must be from the same + release as the `@backstage/core-app-api` package. +- There must be no package that is ahead of the `@backstage/core-app-api` + package. + +* core-app-api +* core-plugin-api +* core-components +* cli +* app-defaults +* backend-common + +### Upgrade order + +Backend upgrades must always be applied before or at the same time as any +frontend upgrades. If frontend and backend upgrades are rolled out +simultaneously there may be brief periods of interruption. + +## Inspiration + +- https://kubernetes.io/releases/version-skew-policy/ +- https://kubernetes.io/docs/reference/using-api/deprecation-policy/ From 26be806db4da32771af1da4e6a66da72a9977714 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 12 Jan 2022 23:01:55 +0100 Subject: [PATCH 2/6] versioning-policy: tweaks + skew policy Co-authored-by: Johan Haals Signed-off-by: Patrik Oldsberg --- docs/overview/versioning-policy.md | 82 ++++++++++-------------------- 1 file changed, 27 insertions(+), 55 deletions(-) diff --git a/docs/overview/versioning-policy.md b/docs/overview/versioning-policy.md index 64f4601ed4..478ab8c722 100644 --- a/docs/overview/versioning-policy.md +++ b/docs/overview/versioning-policy.md @@ -4,7 +4,7 @@ title: Versioning Policy description: --- -## The Purpose +## The Purpose - Release cadence and naming 1.0, 1.1, 1.2, etc. - does not map to semver @@ -12,8 +12,17 @@ description: - X need to be greater then Y or there will be dragons - X is supported for N versions + + ## Backstage releases + + A Backstage release is a manifest of several packages and plugins that work well together. The overarching version of this manifest is decoupled from the individual package versions. @@ -28,7 +37,7 @@ release. ### Main Release Line -Release cadence: Once every 2 months +Current release cadence: Once every 1 months The main release line in versioned with a major and minor version and does not adhere to [semver](https://semver.org). @@ -77,7 +86,7 @@ line, i.e. on version 1.0 or above. may be completely removed. - Security fixes **may** be backported to older releases based on the simplicity of the upgrade path and severity of the vulnerability. -- We promise to do our best to adhere to this policy. +- We will do our best to adhere to this policy. The purpose of the Backstage Stability Index is to communicate the stability of various parts of the project. It is tracked using a scoring system where a @@ -101,58 +110,21 @@ point building on top of the previous one: minor version bump. - **3** - The time limit for the deprecation is 3 months instead of two weeks. -## Release Timeline Example - -- 2022-02-01: 1.0 - - - core-app-api@1.0.2 - - core-plugin-api@1.0.1 - - .. core-app-api@1.0.2-next.0 .. core-app-api@1.0.2-next.1 .. - core-app-api@1.0.2-next.2 .. core-app-api@1.0.2-next.3 - -- 2022-04-01: 1.1 - - - core-app-api@1.1.0 - - core-plugin-api@1.0.1 - - .. core-app-api@1.1.0-next.0 .. core-app-api@1.1.0-next.1 - - .. core-app-api@1.1.1 <- security fix release NOTE: not based on the existing - master, but on 1.1.0 TEST THIS, how does it interact with the `next` release - line? - - .. core-app-api@1.1.1-next.2 <- does this move up to 1.1.1 after the security - release? .. core-app-api@1.1.1-next.3 - -- 2022-06-01: 1.2 - - core-app-api@1.1.2 - - core-plugin-api@1.0.1 - -## Individual Package Policy +## Version Skew Policy In order for Backstage to function properly the following versioning rules must -be followed. +be followed. The rules are referring to the +[Package Architecture](https://backstage.io/docs/overview/architecture-overview#package-architecture). -- If the `@backstage/app-defaults` package is used, it must be from the same - release as the `@backstage/core-app-api` package. -- There must be no package that is ahead of the `@backstage/core-app-api` - package. - -* core-app-api -* core-plugin-api -* core-components -* cli -* app-defaults -* backend-common - -### Upgrade order - -Backend upgrades must always be applied before or at the same time as any -frontend upgrades. If frontend and backend upgrades are rolled out -simultaneously there may be brief periods of interruption. - -## Inspiration - -- https://kubernetes.io/releases/version-skew-policy/ -- https://kubernetes.io/docs/reference/using-api/deprecation-policy/ +- The versions of all the packages in the `Frontend App Core` must be from the + same release, and it is recommended to keep `Common Tooling` on that release + too. +- The Backstage dependencies of any given plugin should be from the same + release. This includes the packages from `Common Libraries`, + `Frontend Plugin Core`, and `Frontend Libraries`, or alternatively the + `Backend Libraries`. +- There must be no package that is from a newer release than the + `Frontend App Core` packages in the app. +- Frontend plugins with a corresponding backend plugin should be from the same + release. The update to the backend plugin **MUST** be deployed before or + together with the update to the frontend plugin. From bdc5114280df0c9f62950a5258c804757c3ebcaa Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Fri, 14 Jan 2022 16:09:09 +0100 Subject: [PATCH 3/6] docs/versioning-policy: switch up the layout and direction of the package versioning policy Co-authored-by: Johan Haals Signed-off-by: Patrik Oldsberg --- docs/overview/versioning-policy.md | 102 ++++++++++++++++++----------- 1 file changed, 62 insertions(+), 40 deletions(-) diff --git a/docs/overview/versioning-policy.md b/docs/overview/versioning-policy.md index 478ab8c722..3026e4ba9d 100644 --- a/docs/overview/versioning-policy.md +++ b/docs/overview/versioning-policy.md @@ -63,54 +63,22 @@ The next release is a weekly snapshot of the project. This is the quickest way to get access to new functionality in Backstage but there is no guarantees around breaking changes in these releases. -## Package versioning - -Every individual package is versioned according to [semver](https://semver.org). -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. - -## Versioning policy +## Versioning Policy The following versioning policy applies to the main release line. The next release line provides no guarantees. -The versioning policy applies to all packages that are part of the main release -line, i.e. on version 1.0 or above. + -- Each release may contain breaking changes, but they will only be done when - necessary and with as low impact as possible. When possible, there will always - be a deprecation path for a breaking change. -- Breaking changes are introduced with a clear upgrade path. -- Deprecations are valid for the duration of a single release, after which they - may be completely removed. +- Each release may contain breaking changes, see the package versioning policy + below for more details. +- Breaking changes in Packages that have reached version `>=1.0.0` will only be + done when necessary and with as low impact as possible. When possible, there + will always be a deprecation path for a breaking change. - Security fixes **may** be backported to older releases based on the simplicity of the upgrade path and severity of the vulnerability. -- We will do our best to adhere to this policy. -The purpose of the Backstage Stability Index is to communicate the stability of -various parts of the project. It is tracked using a scoring system where a -higher score indicates a higher level of stability and is a commitment to -smoother transitions between breaking changes. Importantly, the Stability Index -does not supersede [semver](https://semver.org/), meaning we will still adhere -to semver and only do breaking changes in minor releases as long as we are on -`0.x`. - -Each package or section is assigned a stability score between 0 and 3, with each -point building on top of the previous one: - -- **0** - Breaking changes are noted in the changelog, and documentation is - updated. -- **1** - The changelog entry includes a clearly documented upgrade path, - providing guidance for how to migrate previous usage patterns to the new - version. -- **2** - Breaking changes always include a deprecation phase where both the old - and the new APIs can be used in parallel. This deprecation must have been - released for at least two weeks before the deprecated API is removed in a - minor version bump. -- **3** - The time limit for the deprecation is 3 months instead of two weeks. - -## Version Skew Policy +### Version Skew Policy In order for Backstage to function properly the following versioning rules must be followed. The rules are referring to the @@ -128,3 +96,57 @@ be followed. The rules are referring to the - Frontend plugins with a corresponding backend plugin should be from the same release. The update to the backend plugin **MUST** be deployed before or together with the update to the frontend plugin. + +## Package Versioning Policy + +### Release Stages + +The release stages(`@alpha`, `@beta` `@public`) refers to the +[TSDoc](https://tsdoc.org/) documentation tag of the export, and are also +visible in the API report of each package. + +Backstage uses three stages to indicate the stability for each individual +package export. + +- `@public` is considered stable. +- `@beta` exports will not be publicly visible in the package release. +- `@alpha` here be dragons. Exports will not be publicly visible in the package + release. + +### Package Versioning + +Every individual package is versioned according to [semver](https://semver.org). +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: + +- Breaking changes are noted in the changelog, and documentation is updated. +- Breaking changes are prefixed with `**BREAKING**: ` in the changelog. +- All public exports are considered stable and will have an entry in the + changelog +- Breaking changes are recommended to document a clear upgrade path in the + changelog. This may be omitted for newly introduced or unstable packages. + +In addition, this applies to packages that have reached 1.0.0 or above: + +- All exports are marked with a release stage. +- Breaking changes to stable exports include a deprecation phase if possible. + The deprecation must have been released for at least one mainline release + before it can be removed. +- The release of breaking changes document a clear upgrade path in the + changelog, both when deprecations are introduced and when they are removed. +- Exports that have been marked as `@alpha` or `@beta` may receive breaking + changes without a deprecation period, but the changes must still adhere to + semver. + +For mainline releases: Whether alpha and beta tagged exports need changesets +depends on how we end up releasing them, for example is it a separate version or +separate import? `@backstage/core-plugin-api/alpha`? + +|--------|--------------------------------------------| | | 0.x | >=1.0 | +|--------|--------------------------------------------| | Alpha | changeset - +release | changeset - release | | Beta | changeset - release | changeset - +release | | Public | changeset + guide | deprecation | +|--------|--------------------------------------------| From 9e2ed7022086d0a831043ea65ee34e06a0c68b99 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 17 Jan 2022 14:39:02 +0100 Subject: [PATCH 4/6] docs: finalized initial versioning policy Co-authored-by: blam Co-authored-by: Johan Haals Signed-off-by: Patrik Oldsberg --- docs/overview/versioning-policy.md | 145 +++++++++++++---------------- 1 file changed, 64 insertions(+), 81 deletions(-) diff --git a/docs/overview/versioning-policy.md b/docs/overview/versioning-policy.md index 3026e4ba9d..49a61b85ed 100644 --- a/docs/overview/versioning-policy.md +++ b/docs/overview/versioning-policy.md @@ -4,81 +4,74 @@ title: Versioning Policy description: --- -## The Purpose +The Backstage project is comprised of a set of software components that together +form the Backstage platform. These components are both plugins as well as core +platform libraries and tools. Each component is distributed as a collection of +[packages](), which in the end is +what you end up consuming as an adopter of Backstage. -- Release cadence and naming 1.0, 1.1, 1.2, etc. - - does not map to semver - - Backstage 1.2 is a manifest of multiple versions of packages. -- X need to be greater then Y or there will be dragons -- X is supported for N versions +The number of Backstage packages that build up an application can be quite +large, in the order of hundreds, with just the core platform packages being +counted in the dozen. This creates a challenge for the integrators of a +Backstage project, as there are a lot of moving parts and pieces to keep up to +date. - - -## Backstage releases - - - -A Backstage release is a manifest of several packages and plugins that work well -together. The overarching version of this manifest is decoupled from the -individual package versions. - -There are two different release lines, each with their own versioning policy and -release cadence. The first one is the main release line, which provides -regularly scheduled and releases with high stability. On top of that there is a -Next release line which provides early access to changes in the upcoming main -release. +Our solution to this is collecting our most used components and their packages +into an umbrella version that we call a Backstage release. Each release is a +collection of packages at specific versions that have been verified to work +together. Think of it as a toolbox that comes with batteries included, but you +can always add more plugins and libraries from the open source ecosystem as well +as build your own. ## Release Lines -### Main Release Line +The Backstage project is structured around two different release lines, a +primary "main" release line, and a "next" release line that serves as a preview +and pre-release of the next main-line release. Each of these release lines have +their own release cadence and versioning policy. -Current release cadence: Once every 1 months +## Main Release Line -The main release line in versioned with a major and minor version and does not -adhere to [semver](https://semver.org). +Release cadence: Monthly -The major release if there ever is one, will denote a significant improvement or -change to the Backstage platform. It may come with a large new set of features, -or a switch in the product direction, but other than that it is not different -than a minor release. +The main release line in versioned with a major, minor and patch version but +does **not** adhere to [semver](https://semver.org). The version format is +`..`, for example `1.3.0`. -Minor releases are the most common type of release and the one that is used by -default. Each new minor version can contain new functionality, breaking changes, -and bug fixes. +An increment of the major version denotes a significant improvement or change to +the Backstage platform. It may come with a large new set of features, or a +switch in the product direction. These will be few and far between, and do not +have any set cadence. Policy-wise they are no different than a minor release. -Both major and minor releases are governed by the -[versioning policy](#versioning-policy) in the same way, both of them being -treated as one incremental release. +Each regularly scheduled release will bring an increment to the minor version, +as long as it is not a major release. Each new minor version can contain new +functionality, breaking changes, and bug fixes, according the +[versioning policy](#release-versioning-policy). -### Next Release Line +Patch versions will only be released to address critical bug fixes. They are not +bound to the regular cadence and are instead releases whenever needed. + +## Next Release Line Release cadence: Weekly -The next release is a weekly snapshot of the project. This is the quickest way -to get access to new functionality in Backstage but there is no guarantees -around breaking changes in these releases. +The next release line is a weekly release of the project. Consuming these +releases gives you early access to upcoming functionality in Backstage. There +are however fewer guarantees around breaking changes in these releases, where +moving from one release to the next may introduce significant breaking changes. -## Versioning Policy +## Release Versioning Policy -The following versioning policy applies to the main release line. The next -release line provides no guarantees. +The following versioning policy applies to the main-line releases only. - - -- Each release may contain breaking changes, see the package versioning policy - below for more details. - Breaking changes in Packages that have reached version `>=1.0.0` will only be - done when necessary and with as low impact as possible. When possible, there - will always be a deprecation path for a breaking change. + done when necessary and with the goal of having minimal impact. When possible, + there will always be a deprecation path for a breaking change. - Security fixes **may** be backported to older releases based on the simplicity - of the upgrade path and severity of the vulnerability. + of the upgrade path, and the severity of the vulnerability. +- We will do our best to adhere to this policy. -### Version Skew Policy +### Skew Policy In order for Backstage to function properly the following versioning rules must be followed. The rules are referring to the @@ -99,22 +92,6 @@ be followed. The rules are referring to the ## Package Versioning Policy -### Release Stages - -The release stages(`@alpha`, `@beta` `@public`) refers to the -[TSDoc](https://tsdoc.org/) documentation tag of the export, and are also -visible in the API report of each package. - -Backstage uses three stages to indicate the stability for each individual -package export. - -- `@public` is considered stable. -- `@beta` exports will not be publicly visible in the package release. -- `@alpha` here be dragons. Exports will not be publicly visible in the package - release. - -### Package Versioning - Every individual package is versioned according to [semver](https://semver.org). This versioning is completely decoupled from the Backstage release versioning, meaning you might for example have `@backstage/core-plugin-api` version `3.1.4` @@ -129,9 +106,9 @@ Following versioning policy applies to all packages: - Breaking changes are recommended to document a clear upgrade path in the changelog. This may be omitted for newly introduced or unstable packages. -In addition, this applies to packages that have reached 1.0.0 or above: +For packages at version `1.0.0` or above, the following policy also applies: -- All exports are marked with a release stage. +- All exports are marked with a [release stage](#release-stages). - Breaking changes to stable exports include a deprecation phase if possible. The deprecation must have been released for at least one mainline release before it can be removed. @@ -141,12 +118,18 @@ In addition, this applies to packages that have reached 1.0.0 or above: changes without a deprecation period, but the changes must still adhere to semver. -For mainline releases: Whether alpha and beta tagged exports need changesets -depends on how we end up releasing them, for example is it a separate version or -separate import? `@backstage/core-plugin-api/alpha`? +### Release Stages -|--------|--------------------------------------------| | | 0.x | >=1.0 | -|--------|--------------------------------------------| | Alpha | changeset - -release | changeset - release | | Beta | changeset - release | changeset - -release | | Public | changeset + guide | deprecation | -|--------|--------------------------------------------| +The release stages(`@alpha`, `@beta` `@public`) refers to the +[TSDoc](https://tsdoc.org/) documentation tag of the export, and are also +visible in the API report of each package. + +Backstage uses three stages to indicate the stability for each individual +package export. + +- `@public` - considered stable and are available in the main package entry + point. +- `@beta` - Not visible in the main package entry point, beta exports must be + accessed via `/beta` or `/alpha` imports. +- `@alpha` - here be dragons. Not visible in the main package entry point, alpha + exports must be accessed via `/alpha` imports. From abc0e755ebe38555f677ddf5d42c648c71b5e56c Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 17 Jan 2022 14:49:30 +0100 Subject: [PATCH 5/6] microsite: replace stability index with versioning policy Co-authored-by: Johan Haals Signed-off-by: Patrik Oldsberg --- CONTRIBUTING.md | 2 +- docs/overview/stability-index.md | 340 ------------------- docs/overview/versioning-policy.md | 2 +- microsite/blog/2020-12-22-stability-index.md | 6 +- microsite/sidebars.json | 2 +- mkdocs.yml | 2 +- 6 files changed, 8 insertions(+), 346 deletions(-) delete mode 100644 docs/overview/stability-index.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e853a68ad3..e4aad09207 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -120,7 +120,7 @@ We use [changesets](https://github.com/atlassian/changesets) to help us prepare ### When to use a changeset? -Any time a patch, minor, or major change aligning to [Semantic Versioning](https://semver.org) is made to any published package in `packages/` or `plugins/`, a changeset should be used. It helps to align your change to the [Backstage stability index](https://backstage.io/docs/overview/stability-index) for the package you are changing, for example, when to provide additional clarity on deprecation or impacting changes which will then be included into CHANGELOGs. +Any time a patch, minor, or major change aligning to [Semantic Versioning](https://semver.org) is made to any published package in `packages/` or `plugins/`, a changeset should be used. It helps to align your change to the [Backstage package versioning policy](https://backstage.io/docs/overview/versioning-policy#package-versioning-policy) for the package you are changing, for example, when to provide additional clarity on deprecation or impacting changes which will then be included into CHANGELOGs. In general, changesets are only needed for changes to packages within `packages/` or `plugins/` directories, and only for the packages that are not marked as `private`. Changesets are also not needed for changes that do not affect the published version of each package, for example changes to tests or in-line source code comments. diff --git a/docs/overview/stability-index.md b/docs/overview/stability-index.md deleted file mode 100644 index 9b8983f3c0..0000000000 --- a/docs/overview/stability-index.md +++ /dev/null @@ -1,340 +0,0 @@ ---- -id: stability-index -title: Stability Index -# prettier-ignore -description: An overview of the commitment to stability for different parts of the Backstage codebase. ---- - -## Overview - -The purpose of the Backstage Stability Index is to communicate the stability of -various parts of the project. It is tracked using a scoring system where a -higher score indicates a higher level of stability and is a commitment to -smoother transitions between breaking changes. Importantly, the Stability Index -does not supersede [semver](https://semver.org/), meaning we will still adhere -to semver and only do breaking changes in minor releases as long as we are on -`0.x`. - -Each package or section is assigned a stability score between 0 and 3, with each -point building on top of the previous one: - -- **0** - Breaking changes are noted in the changelog, and documentation is - updated. -- **1** - The changelog entry includes a clearly documented upgrade path, - providing guidance for how to migrate previous usage patterns to the new - version. -- **2** - Breaking changes always include a deprecation phase where both the old - and the new APIs can be used in parallel. This deprecation must have been - released for at least two weeks before the deprecated API is removed in a - minor version bump. -- **3** - The time limit for the deprecation is 3 months instead of two weeks. - -TL;DR: - -- **0** - There's a changelog entry. -- **1** - There's a migration guide. -- **2** - 2 weeks of deprecation. -- **3** - 3 months of deprecation. - -## Packages - -### `example-app` [GitHub](https://github.com/backstage/backstage/tree/master/packages/app/) - -This is the `packages/app` package, and it serves as an example as well as -utility for local development in the main Backstage repo. - -Stability: `N/A` - -### `example-backend` [GitHub](https://github.com/backstage/backstage/tree/master/packages/backend/) - -This is the `packages/backend` package, and it serves as an example as well as -utility for local development in the main Backstage repo. - -Stability: `N/A` - -### `backend-common` [GitHub](https://github.com/backstage/backstage/tree/master/packages/backend-common/) - -A collection of common helpers to be used by both backend plugins, and for -constructing backend packages. - -Stability: `1` - -### `catalog-client` [GitHub](https://github.com/backstage/backstage/tree/master/packages/catalog-client/) - -An HTTP client for interacting with the catalog backend. Usable both in frontend -and Backend. - -Stability: `0`. This is a very new addition and we have some immediate changes -planned. - -### `catalog-model` [GitHub](https://github.com/backstage/backstage/tree/master/packages/catalog-model/) - -Contains the core catalog model, and utilities for working with entities. Usable -both in frontend and Backend. - -Stability: `2`. The catalog model is evolving, but because of the broad usage we - -want to ensure some stability. - -### `cli` [GitHub](https://github.com/backstage/backstage/tree/master/packages/cli/) - -The main toolchain used for Backstage development. The various CLI commands and -options passed to those commands, as well as the environment variables read by -the CLI, are considered to be the interface that the stability index refers to. -The build output may change over time and is not considered a breaking change -unless it is likely to affect external tooling. - -Stability: `2` - -### `cli-common` [GitHub](https://github.com/backstage/backstage/tree/master/packages/cli-common/) - -Lightweight utilities used by the various Backstage CLIs, not intended for -external use. - -Stability: `N/A` - -### `config` [GitHub](https://github.com/backstage/backstage/tree/master/packages/config/) - -Provides the logic and interfaces for reading static configuration. - -Stability: `2` - -### `config-loader` [GitHub](https://github.com/backstage/backstage/tree/master/packages/config-loader/) - -Used to load in static configuration, mainly for use by the CLI and -@backstage/backend-common. - -Stability: `1`. Mainly intended for internal use. - -### `core-app-api` [GitHub](https://github.com/backstage/backstage/tree/master/packages/core-app-api/) - -The APIs used exclusively in the app, such as `createApp` and the system icons. - -Stability: `2`. - -### `core-components` [GitHub](https://github.com/backstage/backstage/tree/master/packages/core-components/) - -A collection of React components for use in Backstage plugins and apps. -Previously exported by `@backstage/core`. - -Stability: `1`. These components have not received a proper review of the API, -but we also want to ensure stability. - -### `core-plugin-api` [GitHub](https://github.com/backstage/backstage/tree/master/packages/core-plugin-api/) - -The core API used to build Backstage plugins and apps. - -Stability: `2`. - -### `cost-insights` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/cost-insights) - -A frontend plugin that allows users to visualize, understand and optimize your -team's cloud costs. - -Stability: `1` - -### `create-app` [GitHub](https://github.com/backstage/backstage/tree/master/packages/create-app/) - -The CLI used to scaffold new Backstage projects. - -Stability: `2` - -### `dev-utils` [GitHub](https://github.com/backstage/backstage/tree/master/packages/dev-utils/) - -Provides utilities for developing plugins in isolation. - -Stability: `0`. This package is largely broken and needs updates. - -### `e2e-test` [GitHub](https://github.com/backstage/backstage/tree/master/packages/e2e-test/) - -Internal CLI utility for running e2e tests. - -Stability: `N/A` - -### `integration` [GitHub](https://github.com/backstage/backstage/tree/master/packages/integration/) - -Provides shared utilities for managing integrations towards different types of -third party systems. This package is currently internal and its functionality -will likely be exposed via separate APIs in the future. - -Some of the functionality in this package is not available elsewhere yes, so if -it's necessary it can be used, but there will be breaking changes. - -Stability: `0` - -### `storybook` [GitHub](https://github.com/backstage/backstage/tree/master/storybook/) - -Internal storybook build for publishing stories to -https://backstage.io/storybook - -Stability: `N/A` - -### `test-utils` [GitHub](https://github.com/backstage/backstage/tree/master/packages/test-utils/) - -Utilities for writing tests for Backstage plugins and apps. - -Stability: `2` - -### `theme` [GitHub](https://github.com/backstage/backstage/tree/master/packages/theme/) - -The core Backstage MUI theme along with customization utilities. - -#### Section: TypeScript - -This is the TypeScript API exported by the theme package. - -Stability: `2` - -#### Section: Visual Theme - -The visual theme exported by the theme packages, where for example changing a -color could be considered a breaking change. - -Stability: `1` - -## Plugins - -Many backend plugins are split into "REST API" and "TypeScript Interface" -sections. The "TypeScript Interface" refers to the API used to integrate the -plugin into the backend. - -Any plugin that is not listed below is untracked and can generally be considered -unstable with a score of `0`. Open a Pull Request if you want your plugin to be -added! - -### `api-docs` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/api-docs/) - -Components to discover and display API entities as an extension to the catalog -plugin. - -Stability: `0` - -### `app-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/app-backend/) - -A backend plugin that can be used to serve the frontend app and inject -configuration. - -Stability: `2` - -### `auth-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/auth-backend/) - -A backend plugin that implements the backend portion of the various -authentication flows used in Backstage. - -#### Section: REST API - -Stability: `2` - -#### Section: TypeScript Interface - -Stability: `1` - -### `catalog` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/catalog/) - -The frontend plugin for the catalog, with the table and building blocks for the -entity pages. - -Stability: `1`. We're planning some work to overhaul how entity pages are -constructed. - -### `catalog-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend/) - -The backend API for the catalog, also exposes the processing subsystem for -customization of the catalog. Powers the @backstage/plugin-catalog frontend -plugin. - -#### Section: REST API - -Stability: `1`. There are plans to remove and rework some endpoints. - -#### Section: TypeScript Interface - -Stability: `1`. There are plans to rework parts of the Processor interface. - -### `catalog-graphql` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/catalog-graphql/) - -Provides the catalog schema and resolvers for the GraphQL backend. - -Stability: `0`. Under heavy development and subject to change. - -### `explore` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/explore/) - -A frontend plugin that introduces the concept of exploring internal and external -tooling in an organization. - -Stability: `0`. Only an example at the moment and not customizable. - -### `graphiql` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/graphiql/) - -Integrates GraphiQL as a tool to browse GraphQL API endpoints inside Backstage. - -Stability: `1` - -### `graphql` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/graphql-backend/) - -A backend plugin that provides - -Stability: `0`. Under heavy development and subject to change. - -### `kubernetes` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/kubernetes/) - -The frontend component of the Kubernetes plugin, used to browse and visualize -Kubernetes resources. - -Stability: `1`. - -### `kubernetes-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/kubernetes-backend/) - -The backend component of the Kubernetes plugin, used to fetch Kubernetes -resources from clusters and associate them with entities in the Catalog. - -Stability: `1`. - -### `proxy-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/proxy-backend/) - -A backend plugin used to set up proxying to other endpoints based on static -configuration. - -Stability: `1` - -### `scaffolder` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/scaffolder/) - -The frontend scaffolder plugin where one can browse templates and initiate -scaffolding jobs. - -Stability: `1` - -### `scaffolder-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend/) - -The backend scaffolder plugin that provides an implementation for templates in -the catalog. - -Stability: `2`. - -### `tech-radar` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/tech-radar/) - -Visualize your company's official guidelines of different areas of software -development. - -Stability: `0` - -### `techdocs` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/techdocs/) - -The frontend component of the TechDocs plugin, used to browse technical -documentation of entities. - -Stability: `1` - -### `techdocs-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend/) - -The backend component of the TechDocs plugin, used to transform and serve -TechDocs. - -Stability: `0` - -### `user-settings` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/user-settings/) - -A frontend plugin that provides a page where the user can tweak various -settings. - -Stability: `1` diff --git a/docs/overview/versioning-policy.md b/docs/overview/versioning-policy.md index 49a61b85ed..8a641cd4a1 100644 --- a/docs/overview/versioning-policy.md +++ b/docs/overview/versioning-policy.md @@ -1,6 +1,6 @@ --- id: versioning-policy -title: Versioning Policy +title: Release & Versioning Policy description: --- diff --git a/microsite/blog/2020-12-22-stability-index.md b/microsite/blog/2020-12-22-stability-index.md index 95074a13a2..e49abb1a35 100644 --- a/microsite/blog/2020-12-22-stability-index.md +++ b/microsite/blog/2020-12-22-stability-index.md @@ -4,7 +4,9 @@ author: Patrik Oldsberg, Spotify authorURL: https://github.com/Rugvip --- -**TL;DR** Backstage is heading out of alpha and moving onto the path to stable releases and an eventual version 1.0. As the community and ecosystem continue to grow at an increasing rate, we want to provide a solid foundation for everyone building things in, with, and around Backstage. So, today we’re introducing the [Stability Index](https://backstage.io/docs/overview/stability-index) — a simple way to find out how likely (or unlikely) a specific package or plugin inside Backstage might be updated with major changes. By indicating the reliability of key features and APIs, this quick reference will help contributors and adopters better plan and coordinate their development efforts going forward. +2022-01 update: The stability is now replaced by the [versioning policy](https://backstage.io/docs/overview/versioning-policy). + +**TL;DR** Backstage is heading out of alpha and moving onto the path to stable releases and an eventual version 1.0. As the community and ecosystem continue to grow at an increasing rate, we want to provide a solid foundation for everyone building things in, with, and around Backstage. So, today we’re introducing the [Stability Index](https://backstage.io/docs/overview/versioning-policy) — a simple way to find out how likely (or unlikely) a specific package or plugin inside Backstage might be updated with major changes. By indicating the reliability of key features and APIs, this quick reference will help contributors and adopters better plan and coordinate their development efforts going forward. ![Animation cycling between stability index scores](assets/2020-12-22/stability-index-hero.gif) @@ -18,7 +20,7 @@ This rapid evolution can create uncertainty around which parts of the project ar In order to tackle the problem of uncertainty, and help align contributors, we have recently introduced a Stability Index. Inspired by a [similar concept with the same name in Node.js](https://nodejs.org/docs/latest-v4.x/api/documentation.html#documentation_stability_index), it’s a score assigned to subsets of the project, indicating the level of maturity of the API and the commitment to backwards compatibility. However, because of the current phase of the project, we have used a slightly different implementation. Rather than the score indicating a perceived stability, a higher score is instead a commitment to providing a smoother upgrade path for users, both through better documentation and backwards compatibility. Importantly, the Stability Index does not supersede [semantic versioning](https://semver.org/) (or semver), meaning we will still adhere to semver and only do breaking changes in minor releases as long as we are on 0.x. -You can find more details about the scores on the [Stability Index](https://backstage.io/docs/overview/stability-index) page, but the following is a TL;DR of the 0–3 scores: +You can find more details about the scores on the [Stability Index](https://backstage.io/docs/overview/versioning-policy) page, but the following is a TL;DR of the 0–3 scores: - **0** — There's a changelog entry. - **1** — There's a migration guide. diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 5369182013..c79615fc47 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -7,7 +7,7 @@ "overview/vision", "overview/background", "overview/adopting", - "overview/stability-index", + "overview/versioning-policy", "overview/support", "overview/glossary", "overview/logos" diff --git a/mkdocs.yml b/mkdocs.yml index 4671a10b7a..1b202eb2f6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,7 +12,7 @@ nav: - Vision: 'overview/vision.md' - The Spotify Story: 'overview/background.md' - Strategies for adopting: 'overview/adopting.md' - - Stability Index: 'overview/stability-index.md' + - Release & Versioning Policy: 'overview/versioning-policy.md' - Support and community: 'overview/support.md' - Glossary: 'overview/glossary.md' - Logo assets: 'overview/logos.md' From 05acf38a67afdf750f47046f91f468b4bfb6d57a Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Fri, 21 Jan 2022 12:38:52 +0100 Subject: [PATCH 6/6] versioning-policy: add bug reporting and fixing policy Signed-off-by: Patrik Oldsberg --- docs/overview/versioning-policy.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/overview/versioning-policy.md b/docs/overview/versioning-policy.md index 8a641cd4a1..7430f3c200 100644 --- a/docs/overview/versioning-policy.md +++ b/docs/overview/versioning-policy.md @@ -69,6 +69,8 @@ The following versioning policy applies to the main-line releases only. there will always be a deprecation path for a breaking change. - Security fixes **may** be backported to older releases based on the simplicity of the upgrade path, and the severity of the vulnerability. +- Bug reports are valid only if reproducible in the most recent release, and bug + fixes are only applied to the next release. - We will do our best to adhere to this policy. ### Skew Policy