microsite: replace stability index with versioning policy
Co-authored-by: Johan Haals <johan.haals@gmail.com> Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
@@ -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`
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
id: versioning-policy
|
||||
title: Versioning Policy
|
||||
title: Release & Versioning Policy
|
||||
description:
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user