|
|
|
@@ -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`
|
Patrik Oldsberg