Merge pull request #8971 from backstage/mob/versioning-policy-wip
[PRFC] Release Process & Versioning Policy
This commit is contained in:
Johan Haals
@@ -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`
|
||||
@@ -0,0 +1,137 @@
|
||||
---
|
||||
id: versioning-policy
|
||||
title: Release & Versioning Policy
|
||||
description:
|
||||
---
|
||||
|
||||
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](<https://en.wikipedia.org/wiki/Npm_(software)>), which in the end is
|
||||
what you end up consuming as an adopter of Backstage.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
## Main Release Line
|
||||
|
||||
Release cadence: Monthly
|
||||
|
||||
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
|
||||
`<major>.<minor>.<patch>`, for example `1.3.0`.
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
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 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.
|
||||
|
||||
## Release Versioning Policy
|
||||
|
||||
The following versioning policy applies to the main-line releases only.
|
||||
|
||||
- Breaking changes in Packages that have reached version `>=1.0.0` will only be
|
||||
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 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
|
||||
|
||||
In order for Backstage to function properly the following versioning rules must
|
||||
be followed. The rules are referring to the
|
||||
[Package Architecture](https://backstage.io/docs/overview/architecture-overview#package-architecture).
|
||||
|
||||
- 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.
|
||||
|
||||
## Package Versioning Policy
|
||||
|
||||
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.
|
||||
|
||||
For packages at version `1.0.0` or above, the following policy also applies:
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
### 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` - 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 `<package-name>/beta` or `<package-name>/alpha` imports.
|
||||
- `@alpha` - here be dragons. Not visible in the main package entry point, alpha
|
||||
exports must be accessed via `<package-name>/alpha` imports.
|
||||
Reference in New Issue
Block a user