| Old name | -New name | -
|---|---|
| GITHUB_ACCESS_TOKEN | -GITHUB_TOKEN | -
| GITHUB_PRIVATE_TOKEN | -GITHUB_TOKEN | -
| GITLAB_ACCESS_TOKEN | -GITLAB_TOKEN | -
| GITLAB_PRIVATE_TOKEN | -GITLAB_TOKEN | -
| AZURE_PRIVATE_TOKEN | -AZURE_TOKEN | -
| GHE_PRIVATE_TOKEN | -GHE_TOKEN | -
+
+> Note: See below for our recommended deployment architecture which takes care
+> of stability, scalability and speed.
+
+When you open a TechDocs site in Backstage, the
+[TechDocs Reader](./concepts.md#techdocs-reader) makes a request to
+`techdocs-backend` with the entity ID and the path of the current page you are
+looking at. In response, it receives the static files (HTML, CSS, JSON, etc.) to
+render on the page in TechDocs/Backstage.
+
+The static files consist of HTML, CSS and Images generated by MkDocs. We remove
+all the JavaScript before adding them to Backstage for security reasons. And
+there are some additional techdocs metadata JSON files that TechDocs needs to
+render a site.
+
+The TechDocs Reader then applies a list of "Transformers" (see
+[Concepts](./concepts.md)) which modify the generated static HTML files for a
+number of use cases e.g. Remove certain headers, filter out some HTML tags, etc.
+
+Currently, we use the Backstage server's (or techdocs-backend's) local file
+system to store the generated files. Publishing to an external storage system
+(AWS S3, GCS, etc.) is also possible, but has not been implemented yet.
+
+A word about `UrlReader` vs Git preparer - Right now, we have two ways to fetch
+files from its source repository for docs site generation. 1. By using Git
+and 2. By directly using Source control (GitHub, Azure, etc.) APIs. This work is
+heavily in progress. Please reach out to us on Discord in the #docs-like-code
+channel to talk about it.
+
+## Recommended deployment
+
+This is how we recommend deploying TechDocs in production environment.
+
+
+
+The key difference in the recommended deployment approach is where the docs are
+built.
+
+We assume each entity lives in a repository somewhere (GitHub, GitLab, etc.). We
+recommend using a CI/CD pipeline with the repository that has a dedicated
+step/job to generate docs for TechDocs. The generated static files are then
+stored in a cloud storage solution of your choice.
+[Track progress here](https://github.com/backstage/backstage/issues/3096).
+
+Similar to how it is done in the Basic setup, the TechDocs Reader requests
+`techdocs-backend` plugin for the docs site. `techdocs-backend` then requests
+your configured storage solution for the necessary files and returns them to
+TechDocs Reader.
+
+We will provide instructions, scripts and/or templates (e.g. GitHub Actions) to
+generate docs in your CI/CD system.
+[Track progress here.](https://github.com/backstage/backstage/issues/3400) You
+will be able to use `techdocs-cli` to generate docs and publish the generated
+docs site files to your cloud storage system.
+
+Note about caching: We have noticed internally that some storage providers can
+be quite slow, which is why we are recommending a cache that sits between the
+TechDocs Reader and the Storage.
+
+_Feel free to suggest better ideas to us in #docs-like-code channel in Discord
+or via a GitHub issue._
+
+### Security consideration
+
+Our biggest security concern is managing the access to the docs in the cloud
+storage. We also want to have only one security solution for all different types
+of storage (GCS, AWS, custom SFTP server, etc.) Restricting access to the
+storage and only allowing `techdocs-backend` to fetch files is a good way to
+achieve this.
+
+This would also allow us to use the access control management Backstage when
+that is ready.
+[Track progress here.](https://github.com/backstage/backstage/issues/3218)
+
+In theory, you can directly enable TechDocs Reader to read from your storage.
+But, you will have to think about how to do it without the docs being public and
+how access to user groups is managed.
+
+For cloud storage access tokens, `techdocs-backend` only needs a token with Read
+permissions. But in your CI/CD system, there needs to be a token with Write
+permissions to publish the generated docs site files.
+
+## FAQs
+
+**Q: Why do you have separate "basic" and "recommended" deployment approaches?**
+
+A: The basic or out-of-the-box setup is what you get when you create a new app
+or do a git clone of the Backstage repository. We want the first experience to
+_just work magically_ so that you can have your first experience with TechDocs
+which is smooth. However, if you decide to deploy Backstage/TechDocs for
+production use, the basic setup would work but there are going to be downsides
+as you scale with the number of documentation sites and sizes of them. So you
+would want to make sure the deployment is as stable as possible. Hence there is
+a recommended approach. There can be even more deployment approaches to TechDocs
+and we welcome such "Alternative" ideas from the community.
+
+**Q: Why don't you recommend techdocs-backend local filesystem to serve static
+files?**
+
+A: It would make scaling a Backstage instance harder. Think about the case where
+we have distributed Backstage deployments. Using a separate file storage system
+for TechDocs makes it easier to do some operations like delete a docs site and
+wipe its contents.
+
+**Q: Why aren't docs built on the fly i.e. when users visits a page, generate
+docs site in real-time?**
+
+A: Generating the content from Markdown on the fly is not optimal (although that
+is how the basic out-of-the-box setup is implemented). Storage solutions act as
+a cache for the generated static content. TechDocs is also currently built on
+MkDocs which does not allow us to generate docs per-page, so we would have to
+build all docs for a entity on every request.
+
+# Future work
+
+_Ideas here are far fetched and not in the project's milestone for near future
+(~6 months)._
+
+We currently depend on MkDocs to parse doc sites written in Markdown. And we
+store the generated static assets and re-use it later to render in Backstage. A
+better (futuristic) approach will be to directly parse whatever type of source
+files you have in your docs repository and directly render in Backstage in
+real-time.
+
+# Features status
+
+Status of all the features mentioned above.
+
+**In place ✅**
+
+- Basic setup with techdocs-backend file server as storage.
+- Basic setup with cloud storage solution.
+
+**Work in progress 🚧**
+
+- `techdocs-cli` is able to generate docs in CI/CD environment.
+- `techdocs-cli` is able to publish docs site to any storage.
+
+**Not implemented yet ❌**
+
+- `techdocs-backend` integration with Backstage access control management.
diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md
index 13144f8df0..26254a7e12 100644
--- a/docs/features/techdocs/concepts.md
+++ b/docs/features/techdocs/concepts.md
@@ -8,42 +8,71 @@ Spotify's docs-like-code solution in Backstage
This page describes concepts that are introduced with Spotify's docs-like-code
solution in Backstage.
-### TechDocs Core Plugin
+## Generating TechDocs Steps
-The TechDocs Core Plugin is an [MkDocs](https://www.mkdocs.org/) plugin created
-as a wrapper around multiple MkDocs plugins and Python Markdown extensions to
-standardize the configuration of MkDocs used for TechDocs.
+### TechDocs Preparer
-[TechDocs Core](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/techdocs-core/README.md)
+Preparing is the first step of generating documentation for an entity. It
+fetches the source markdown files from the source code hosting provider (GitHub,
+GitLab, etc.) and passes the files to the generator for next steps.
-### TechDocs container
+There are two kinds of preparers available -
+
+1. Common Git Preparer - Uses `git clone` on any repository url.
+2. Url Reader - Uses source code hosting provider's API to download files.
+ (Faster and recommended)
+
+### TechDocs Generator
+
+Generating is the second step after preparing the markdown source files. This
+step either runs the TechDocs container (defined below) or runs `mkdocs` CLI to
+generate static HTML files and its assets.
+
+### TechDocs Publisher
+
+Publishing is the third and final step after preparing and generating docs.
+TechDocs Publisher uploads the generated files to a storage.
+
+The `techdocs-backend` plugin currently comes with two publishers - Google Cloud
+Storage and Local Filesystem. You can configure them in your Backstage app.
+[See here](./configuration.md).
+
+A TechDocs publisher is responsible for two things (two-way communication
+between `techdocs-backend` and the storage)
+
+1. Publish generated static files to a storage (Configured by
+ `techdocs.builder`)
+2. Read files from the storage when users visit a TechDocs site
+
+[TechDocs Backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend)
+
+## TechDocs Container
The TechDocs container is a Docker container available at
[DockerHub](https://hub.docker.com/r/spotify/techdocs). It builds static HTML
pages, including stylesheets and scripts from Python flavored Markdown, through
MkDocs.
-[TechDocs Container](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/README.md)
+[TechDocs Container](https://github.com/backstage/techdocs-container)
-### TechDocs publisher
+## TechDocs Core Plugin
-The `techdocs-backend` plugin currently comes with one publisher -
-`LocalPublish`.
+The TechDocs Core Plugin is an [MkDocs](https://www.mkdocs.org/) plugin created
+as a wrapper around multiple MkDocs plugins and Python Markdown extensions to
+standardize the configuration of MkDocs used for TechDocs.
-[TechDocs Backend](https://github.com/spotify/backstage/tree/master/plugins/techdocs-backend)
+[TechDocs Core](https://github.com/backstage/mkdocs-techdocs-core)
-More standalone publishers will come in the near future...
-
-### TechDocs CLI
+## TechDocs CLI
The TechDocs CLI was created to make it easy to write, generate and preview
documentation for publishing. Currently it mostly acts as a wrapper around the
TechDocs container and provides an easy-to-use interface for our docker
container.
-[TechDocs CLI](https://github.com/spotify/backstage/blob/master/packages/techdocs-cli/README.md)
+[TechDocs CLI](https://github.com/backstage/techdocs-cli)
-### TechDocs Reader
+## TechDocs Reader
Documentation generated by TechDocs is generated as static HTML sites. The
TechDocs Reader was therefore created to be able to integrate pre-generated HTML
@@ -53,13 +82,13 @@ The TechDocs Reader purpose is also to open up the opportunity to integrate
TechDocs widgets for a customized full-featured TechDocs experience.
([coming soon V.3](./README.md#project-roadmap))
-[TechDocs Reader](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/README.md)
+[TechDocs Reader](https://github.com/backstage/backstage/blob/master/plugins/techdocs/src/reader/README.md)
-### Transformers
+## Transformers
Transformers are different pieces of functionality used inside the TechDocs
Reader. The reason why transformers were introduced was to provide a way to
transform the HTML content on pre and post render (e.g. rewrite docs links or
modify css).
-[Transformers API docs](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/README.md)
+[Transformers API docs](https://github.com/backstage/backstage/blob/master/plugins/techdocs/src/reader/README.md)
diff --git a/docs/features/techdocs/configuration.md b/docs/features/techdocs/configuration.md
new file mode 100644
index 0000000000..b3cb349778
--- /dev/null
+++ b/docs/features/techdocs/configuration.md
@@ -0,0 +1,73 @@
+---
+id: configuration
+title: TechDocs Configuration Options
+description:
+ Reference documentation for configuring TechDocs using app-config.yaml
+---
+
+Using the `app-config.yaml` in the Backstage app, you can configure TechDocs
+using several options. This page serves as a reference to all the available
+configuration options for TechDocs.
+
+```yaml
+# File: app-config.yaml
+
+techdocs:
+
+ # TechDocs makes API calls to techdocs-backend using this URL. e.g. get docs of an entity, get metadata, etc.
+
+ requestUrl: http://localhost:7000/api/techdocs
+
+
+ # Just another route in techdocs-backend where TechDocs requests the static files from. This URL uses an HTTP middleware
+ # to serve files from either a local directory or an External storage provider.
+
+ storageUrl: http://localhost:7000/api/techdocs/static/docs
+
+
+ # generators.techdocs can have two values: 'docker' or 'local'. This is to determine how to run the generator - whether to
+ # spin up the techdocs-container docker image or to run mkdocs locally (assuming all the dependencies are taken care of).
+ # You want to change this to 'local' if you are running Backstage using your own custom Docker setup and want to avoid running
+ # into Docker in Docker situation. Read more here
+ # https://backstage.io/docs/features/techdocs/getting-started#disable-docker-in-docker-situation-optional
+
+ generators:
+ techdocs: 'docker'
+
+
+ # techdocs.builder can be either 'local' or 'external.
+ # If builder is set to 'local' and you open a TechDocs page, techdocs-backend will try to generate the docs, publish to storage
+ # and show the generated docs afterwords. This is the "Basic" setup of the TechDocs Architecture.
+ # If builder is set to 'external', techdocs-backend will only fetch the docs and will NOT try to generate and publish. In this case of 'external',
+ # we assume that docs are being built by an external process (e.g. in the CI/CD pipeline of the repository). This is the "Recommended" setup of
+ # the architecture. Read more here https://backstage.io/docs/features/techdocs/architecture
+
+ builder: 'local'
+
+
+ # techdocs.publisher is used to configure the Storage option, whether you want to use the local filesystem to store generated docs
+ # or you want to use External storage providers like Google Cloud Storage, AWS S3, etc.
+
+ publisher:
+
+ # techdocs.publisher.type can be - 'local' or 'googleGcs' (awsS3, azureStorage, etc. to be available as well).
+ # When set to 'local', techdocs-backend will create a 'static' directory at its root to store generated documentation files.
+ # When set to 'googleGcs', techdocs-backend will use a Google Cloud Storage Bucket to store generated documentation files.
+
+ type: 'local'
+
+
+ # Required when techdocs.publisher.type is set to 'googleGcs'. Skip otherwise.
+
+ googleGcs:
+ # An API key is required to write to a storage bucket.
+ credentials:
+ $file: '/path/to/google_application_credentials.json',
+
+ # Your GCP Project ID where the Cloud Storage Bucket is hosted.
+ projectId: 'gcp-project-id'
+
+ # Cloud Storage Bucket Name
+ bucketName: 'techdocs-storage',
+
+```
diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md
index 38f452dcf3..187fe97aed 100644
--- a/docs/features/techdocs/creating-and-publishing.md
+++ b/docs/features/techdocs/creating-and-publishing.md
@@ -41,7 +41,7 @@ setup for free.
### Manually add documentation setup to already existing repository
-Prerequisities:
+Prerequisites:
- An existing component
[registered in backstage](../software-catalog/index.md#adding-components-to-the-catalog)
diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md
index 72efb6eee0..e1ddfd23f9 100644
--- a/docs/features/techdocs/getting-started.md
+++ b/docs/features/techdocs/getting-started.md
@@ -1,7 +1,7 @@
---
id: getting-started
title: Getting Started
-description: Getting Started Guidelines
+description: Getting Started Documentation
---
TechDocs functions as a plugin to Backstage, so you will need to use Backstage
@@ -10,50 +10,147 @@ to use TechDocs.
If you haven't setup Backstage already, start
[here](../../getting-started/index.md).
-## Installing TechDocs
+> If you used `npx @backstage/create-app`, TechDocs may already be present.
+>
+> You should skip to [`Setting the Configuration`](#setting-the-configuration)
+> below.
-TechDocs is provided with the Backstage application by default. If you want to
-set up TechDocs manually, keep following the instructions below.
-
-### Adding the package
+## Adding TechDocs frontend plugin
The first step is to add the TechDocs plugin to your Backstage application.
-Navigate to your new Backstage application folder:
-
-```bash
-cd hello-world/
-```
-
-Then navigate to your `packages/app` folder to install TechDocs:
+Navigate to your new Backstage application directory. And then to your
+`packages/app` directory, and install the `@backstage/plugin-techdocs` package.
```bash
+cd my-backstage-app/
cd packages/app
yarn add @backstage/plugin-techdocs
```
-After a short while, the TechDocs plugin should be successfully installed.
+Once the package has been installed, you need to import the plugin in your app.
-Next, you need to set up some basic configuration. Enter the following command:
-
-```bash
-yarn install
-```
-
-Add this to `packages/app/src/plugins.ts`:
+Add the following to `packages/app/src/plugins.ts`:
```typescript
export { plugin as TechDocs } from '@backstage/plugin-techdocs';
```
-### Setting the configuration
+Now let us embed the TechDocs router in our main Backstage frontend router. In
+`packages/app/src/App.tsx`, import the TechDocs router and add the following to
+`AppRoutes`:
-TechDocs allows for configuration of the docs storage URL through your
-`app-config.yaml` file. We provide two different values to be configured,
-`requestUrl` and `storageUrl`. The `requestUrl` is what the reader will request
-its data from, and `storageUrl` is where the backend can find the stored
-documentation.
+```tsx
+import { Router as DocsRouter } from '@backstage/plugin-techdocs';
-The default storage and request URLs:
+// ...
+
+const AppRoutes = () => {
+
export interface BackstageTheme extends Theme {
palette: BackstagePalette;
+ page: PageTheme;
+ getPageTheme: ({ themeId }: PageThemeSelector) => PageTheme;
}
Defined at
-[packages/theme/src/types.ts:73](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/theme/src/types.ts#L73).
+[packages/theme/src/types.ts:81](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/theme/src/types.ts#L81).
Referenced by: [AppTheme](#apptheme).
@@ -129,13 +136,13 @@ export type Observable<T> = {
Defined at
-[packages/core-api/src/types.ts:53](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L53).
+[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L53).
Referenced by: [activeThemeId\$](#activethemeid).
### Observer
-This file contains non-react related core types used through Backstage.
+This file contains non-react related core types used throughout Backstage.
Observer interface for consuming an Observer, see TC39.
@@ -148,10 +155,38 @@ export type Observer<T> = {
Defined at
-[packages/core-api/src/types.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L24).
+[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L24).
Referenced by: [Observable](#observable).
+### PageTheme
+
+
+export type PageTheme = {
+ colors: string[];
+ shape: string;
+ backgroundImage: string;
+}
+
+
+Defined at
+[packages/theme/src/types.ts:103](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/theme/src/types.ts#L103).
+
+Referenced by: [BackstageTheme](#backstagetheme).
+
+### PageThemeSelector
+
+
+export type PageThemeSelector = {
+ themeId: string;
+}
+
+
+Defined at
+[packages/theme/src/types.ts:77](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/theme/src/types.ts#L77).
+
+Referenced by: [BackstageTheme](#backstagetheme).
+
### PaletteAdditions
@@ -181,6 +216,8 @@ type PaletteAdditions = {
navigation: {
background: string;
indicator: string;
+ color: string;
+ selectedColor: string;
};
tabbar: {
indicator: string;
@@ -199,12 +236,14 @@ type PaletteAdditions = {
banner: {
info: string;
error: string;
+ text: string;
+ link: string;
};
}
Defined at
-[packages/theme/src/types.ts:23](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/theme/src/types.ts#L23).
+[packages/theme/src/types.ts:23](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/theme/src/types.ts#L23).
Referenced by: [BackstagePalette](#backstagepalette).
@@ -227,6 +266,6 @@ export type Subscription = {
Defined at
-[packages/core-api/src/types.ts:33](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L33).
+[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L33).
Referenced by: [Observable](#observable).
diff --git a/docs/reference/utility-apis/BackstageIdentityApi.md b/docs/reference/utility-apis/BackstageIdentityApi.md
index 529b73c576..dafdb7d55f 100644
--- a/docs/reference/utility-apis/BackstageIdentityApi.md
+++ b/docs/reference/utility-apis/BackstageIdentityApi.md
@@ -1,7 +1,7 @@
# BackstageIdentityApi
The BackstageIdentityApi type is defined at
-[packages/core-api/src/apis/definitions/auth.ts:134](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L134).
+[packages/core-api/src/apis/definitions/auth.ts:134](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L134).
The following Utility APIs implement this type:
@@ -19,6 +19,8 @@ The following Utility APIs implement this type:
- [oktaAuthApiRef](./README.md#oktaauth)
+- [samlAuthApiRef](./README.md#samlauth)
+
## Members
### getBackstageIdentity()
@@ -68,7 +70,7 @@ export type AuthRequestOptions = {
Defined at
-[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L40).
+[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L40).
Referenced by: [getBackstageIdentity](#getbackstageidentity).
@@ -89,6 +91,6 @@ export type BackstageIdentity = {
Defined at
-[packages/core-api/src/apis/definitions/auth.ts:147](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L147).
+[packages/core-api/src/apis/definitions/auth.ts:147](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L147).
Referenced by: [getBackstageIdentity](#getbackstageidentity).
diff --git a/docs/reference/utility-apis/Config.md b/docs/reference/utility-apis/Config.md
index b54e122c03..2ae047a700 100644
--- a/docs/reference/utility-apis/Config.md
+++ b/docs/reference/utility-apis/Config.md
@@ -1,7 +1,7 @@
# Config
The Config type is defined at
-[packages/config/src/types.ts:32](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/config/src/types.ts#L32).
+[packages/config/src/types.ts:32](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/config/src/types.ts#L32).
The following Utility API implements this type:
[configApiRef](./README.md#config)
@@ -140,7 +140,7 @@ export type Config = {
Defined at
-[packages/config/src/types.ts:32](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/config/src/types.ts#L32).
+[packages/config/src/types.ts:32](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/config/src/types.ts#L32).
Referenced by: [getConfig](#getconfig), [getOptionalConfig](#getoptionalconfig),
[getConfigArray](#getconfigarray),
@@ -153,7 +153,7 @@ export type JsonArray = JsonValue[]
Defined at
-[packages/config/src/types.ts:18](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/config/src/types.ts#L18).
+[packages/config/src/types.ts:18](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/config/src/types.ts#L18).
Referenced by: [JsonValue](#jsonvalue).
@@ -164,7 +164,7 @@ export type JsonObject = { [key in string]?: JsonValue
Defined at
-[packages/config/src/types.ts:17](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/config/src/types.ts#L17).
+[packages/config/src/types.ts:17](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/config/src/types.ts#L17).
Referenced by: [JsonValue](#jsonvalue).
@@ -181,7 +181,7 @@ export type JsonValue =
Defined at
-[packages/config/src/types.ts:19](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/config/src/types.ts#L19).
+[packages/config/src/types.ts:19](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/config/src/types.ts#L19).
Referenced by: [get](#get), [getOptional](#getoptional),
[JsonObject](#jsonobject), [JsonArray](#jsonarray), [Config](#config).
diff --git a/docs/reference/utility-apis/DiscoveryApi.md b/docs/reference/utility-apis/DiscoveryApi.md
index 24371c1729..ac278fdd97 100644
--- a/docs/reference/utility-apis/DiscoveryApi.md
+++ b/docs/reference/utility-apis/DiscoveryApi.md
@@ -1,7 +1,7 @@
# DiscoveryApi
The DiscoveryApi type is defined at
-[packages/core-api/src/apis/definitions/DiscoveryApi.ts:30](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L30).
+[packages/core-api/src/apis/definitions/DiscoveryApi.ts:30](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L30).
The following Utility API implements this type:
[discoveryApiRef](./README.md#discovery)
diff --git a/docs/reference/utility-apis/ErrorApi.md b/docs/reference/utility-apis/ErrorApi.md
index 762d2016d5..93f4f9cd48 100644
--- a/docs/reference/utility-apis/ErrorApi.md
+++ b/docs/reference/utility-apis/ErrorApi.md
@@ -1,7 +1,7 @@
# ErrorApi
The ErrorApi type is defined at
-[packages/core-api/src/apis/definitions/ErrorApi.ts:53](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/ErrorApi.ts#L53).
+[packages/core-api/src/apis/definitions/ErrorApi.ts:53](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/ErrorApi.ts#L53).
The following Utility API implements this type: [errorApiRef](./README.md#error)
@@ -41,7 +41,7 @@ type Error = {
Defined at
-[packages/core-api/src/apis/definitions/ErrorApi.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/ErrorApi.ts#L24).
+[packages/core-api/src/apis/definitions/ErrorApi.ts:24](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/ErrorApi.ts#L24).
Referenced by: [post](#post), [error\$](#error).
@@ -58,7 +58,7 @@ export type ErrorContext = {
Defined at
-[packages/core-api/src/apis/definitions/ErrorApi.ts:33](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/ErrorApi.ts#L33).
+[packages/core-api/src/apis/definitions/ErrorApi.ts:33](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/ErrorApi.ts#L33).
Referenced by: [post](#post), [error\$](#error).
@@ -87,13 +87,13 @@ export type Observable<T> = {
Defined at
-[packages/core-api/src/types.ts:53](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L53).
+[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L53).
Referenced by: [error\$](#error).
### Observer
-This file contains non-react related core types used through Backstage.
+This file contains non-react related core types used throughout Backstage.
Observer interface for consuming an Observer, see TC39.
@@ -106,7 +106,7 @@ export type Observer<T> = {
Defined at
-[packages/core-api/src/types.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L24).
+[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L24).
Referenced by: [Observable](#observable).
@@ -129,6 +129,6 @@ export type Subscription = {
Defined at
-[packages/core-api/src/types.ts:33](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L33).
+[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L33).
Referenced by: [Observable](#observable).
diff --git a/docs/reference/utility-apis/FeatureFlagsApi.md b/docs/reference/utility-apis/FeatureFlagsApi.md
index 8fbcb794fb..529d2ac5dc 100644
--- a/docs/reference/utility-apis/FeatureFlagsApi.md
+++ b/docs/reference/utility-apis/FeatureFlagsApi.md
@@ -1,27 +1,20 @@
# FeatureFlagsApi
The FeatureFlagsApi type is defined at
-[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:41](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L41).
+[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:60](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L60).
The following Utility API implements this type:
[featureFlagsApiRef](./README.md#featureflags)
## Members
-### registeredFeatureFlags
+### registerFlag()
-Store a list of registered feature flags.
+Registers a new feature flag. Once a feature flag has been registered it can be
+toggled by users, and read back to enable or disable features.
-registeredFeatureFlags: FeatureFlagsRegistryItem[] -- -### getFlags() - -Get a list of all feature flags from the current user. - -
-getFlags(): UserFlags +registerFlag(flag: FeatureFlag): void### getRegisteredFlags() @@ -29,5 +22,92 @@ getFlags(): UserFlags Get a list of all registered flags.
-getRegisteredFlags(): FeatureFlagsRegistry +getRegisteredFlags(): FeatureFlag[]+ +### isActive() + +Whether the feature flag with the given name is currently activated for the +user. + +
+isActive(name: string): boolean ++ +### save() + +Save the user's choice of feature flag states. + +
+save(options: FeatureFlagsSaveOptions): void ++ +## Supporting types + +These types are part of the API declaration, but may not be unique to this API. + +### FeatureFlag + +The feature flags API is used to toggle functionality to users across plugins +and Backstage. + +Plugins can use this API to register feature flags that they have available for +users to enable/disable, and this API will centralize the current user's state +of which feature flags they would like to enable. + +This is ideal for Backstage plugins, as well as your own App, to trial +incomplete or unstable upcoming features. Although there will be a common +interface for users to enable and disable feature flags, this API acts as +another way to enable/disable. + +
+export type FeatureFlag = {
+ name: string;
+ pluginId: string;
+}
+
+
+Defined at
+[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:31](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L31).
+
+Referenced by: [registerFlag](#registerflag),
+[getRegisteredFlags](#getregisteredflags).
+
+### FeatureFlagState
+
+
+export enum FeatureFlagState {
+ None = 0,
+ Active = 1,
+}
+
+
+Defined at
+[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:36](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L36).
+
+Referenced by: [FeatureFlagsSaveOptions](#featureflagssaveoptions).
+
+### FeatureFlagsSaveOptions
+
+Options to use when saving feature flags.
+
+
+export type FeatureFlagsSaveOptions = {
+ /**
+ * The new feature flag states to save.
+ */
+ states: Record<string, FeatureFlagState>;
+
+ /**
+ * Whether the saves states should be merged into the existing ones, or replace them.
+ *
+ * Defaults to false.
+ */
+ merge?: boolean;
+}
+
+
+Defined at
+[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:44](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L44).
+
+Referenced by: [save](#save).
diff --git a/docs/reference/utility-apis/IdentityApi.md b/docs/reference/utility-apis/IdentityApi.md
index 5ee5c582b6..a88aaf0b8a 100644
--- a/docs/reference/utility-apis/IdentityApi.md
+++ b/docs/reference/utility-apis/IdentityApi.md
@@ -1,7 +1,7 @@
# IdentityApi
The IdentityApi type is defined at
-[packages/core-api/src/apis/definitions/IdentityApi.ts:22](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/IdentityApi.ts#L22).
+[packages/core-api/src/apis/definitions/IdentityApi.ts:22](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/IdentityApi.ts#L22).
The following Utility API implements this type:
[identityApiRef](./README.md#identity)
@@ -76,6 +76,6 @@ export type ProfileInfo = {
Defined at
-[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L162).
+[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L162).
Referenced by: [getProfile](#getprofile).
diff --git a/docs/reference/utility-apis/OAuthApi.md b/docs/reference/utility-apis/OAuthApi.md
index a489db76c5..79b55812ef 100644
--- a/docs/reference/utility-apis/OAuthApi.md
+++ b/docs/reference/utility-apis/OAuthApi.md
@@ -1,7 +1,7 @@
# OAuthApi
The OAuthApi type is defined at
-[packages/core-api/src/apis/definitions/auth.ts:67](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L67).
+[packages/core-api/src/apis/definitions/auth.ts:67](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L67).
The following Utility APIs implement this type:
@@ -82,7 +82,7 @@ export type AuthRequestOptions = {
Defined at
-[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L40).
+[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L40).
Referenced by: [getAccessToken](#getaccesstoken).
@@ -108,6 +108,6 @@ export type OAuthScope = string | string[]
Defined at
-[packages/core-api/src/apis/definitions/auth.ts:38](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L38).
+[packages/core-api/src/apis/definitions/auth.ts:38](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L38).
Referenced by: [getAccessToken](#getaccesstoken).
diff --git a/docs/reference/utility-apis/OAuthRequestApi.md b/docs/reference/utility-apis/OAuthRequestApi.md
index 1328aabeec..f1c2311ce9 100644
--- a/docs/reference/utility-apis/OAuthRequestApi.md
+++ b/docs/reference/utility-apis/OAuthRequestApi.md
@@ -1,7 +1,7 @@
# OAuthRequestApi
The OAuthRequestApi type is defined at
-[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:99](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L99).
+[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:99](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L99).
The following Utility API implements this type:
[oauthRequestApiRef](./README.md#oauthrequest)
@@ -73,7 +73,7 @@ export type AuthProvider = {
Defined at
-[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:27](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L27).
+[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:27](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L27).
Referenced by: [AuthRequesterOptions](#authrequesteroptions),
[PendingAuthRequest](#pendingauthrequest).
@@ -97,7 +97,7 @@ export type AuthRequester<AuthResponse> = (
Defined at
-[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:66](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L66).
+[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:66](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L66).
Referenced by: [createAuthRequester](#createauthrequester).
@@ -122,7 +122,7 @@ export type AuthRequesterOptions<AuthResponse> = {
Defined at
-[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:43](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L43).
+[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:43](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L43).
Referenced by: [createAuthRequester](#createauthrequester).
@@ -151,13 +151,13 @@ export type Observable<T> = {
Defined at
-[packages/core-api/src/types.ts:53](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L53).
+[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L53).
Referenced by: [authRequest\$](#authrequest).
### Observer
-This file contains non-react related core types used through Backstage.
+This file contains non-react related core types used throughout Backstage.
Observer interface for consuming an Observer, see TC39.
@@ -170,7 +170,7 @@ export type Observer<T> = {
Defined at
-[packages/core-api/src/types.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L24).
+[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L24).
Referenced by: [Observable](#observable).
@@ -205,7 +205,7 @@ export type PendingAuthRequest = {
Defined at
-[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:77](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L77).
+[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:77](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L77).
Referenced by: [authRequest\$](#authrequest).
@@ -228,6 +228,6 @@ export type Subscription = {
Defined at
-[packages/core-api/src/types.ts:33](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L33).
+[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L33).
Referenced by: [Observable](#observable).
diff --git a/docs/reference/utility-apis/OpenIdConnectApi.md b/docs/reference/utility-apis/OpenIdConnectApi.md
index efd79593d6..eaea530708 100644
--- a/docs/reference/utility-apis/OpenIdConnectApi.md
+++ b/docs/reference/utility-apis/OpenIdConnectApi.md
@@ -1,7 +1,7 @@
# OpenIdConnectApi
The OpenIdConnectApi type is defined at
-[packages/core-api/src/apis/definitions/auth.ts:99](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L99).
+[packages/core-api/src/apis/definitions/auth.ts:99](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L99).
The following Utility APIs implement this type:
@@ -66,6 +66,6 @@ export type AuthRequestOptions = {
Defined at
-[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L40).
+[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L40).
Referenced by: [getIdToken](#getidtoken).
diff --git a/docs/reference/utility-apis/ProfileInfoApi.md b/docs/reference/utility-apis/ProfileInfoApi.md
index 402b5ba504..76d04045e8 100644
--- a/docs/reference/utility-apis/ProfileInfoApi.md
+++ b/docs/reference/utility-apis/ProfileInfoApi.md
@@ -1,7 +1,7 @@
# ProfileInfoApi
The ProfileInfoApi type is defined at
-[packages/core-api/src/apis/definitions/auth.ts:117](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L117).
+[packages/core-api/src/apis/definitions/auth.ts:117](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L117).
The following Utility APIs implement this type:
@@ -19,6 +19,8 @@ The following Utility APIs implement this type:
- [oktaAuthApiRef](./README.md#oktaauth)
+- [samlAuthApiRef](./README.md#samlauth)
+
## Members
### getProfile()
@@ -65,7 +67,7 @@ export type AuthRequestOptions = {
Defined at
-[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L40).
+[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L40).
Referenced by: [getProfile](#getprofile).
@@ -93,6 +95,6 @@ export type ProfileInfo = {
Defined at
-[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L162).
+[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L162).
Referenced by: [getProfile](#getprofile).
diff --git a/docs/reference/utility-apis/README.md b/docs/reference/utility-apis/README.md
index 71931a5d5a..1ef5b6197e 100644
--- a/docs/reference/utility-apis/README.md
+++ b/docs/reference/utility-apis/README.md
@@ -3,7 +3,7 @@
The following is a list of all Utility APIs defined by `@backstage/core`. They
are available to use by plugins and components, and can be accessed using the
`useApi` hook, also provided by `@backstage/core`. For more information, see
-https://github.com/spotify/backstage/blob/master/docs/api/utility-apis.md.
+https://github.com/backstage/backstage/blob/master/docs/api/utility-apis.md.
### alert
@@ -12,7 +12,7 @@ Used to report alerts and forward them to the app
Implemented type: [AlertApi](./AlertApi.md)
ApiRef:
-[alertApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/AlertApi.ts#L41)
+[alertApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/AlertApi.ts#L41)
### appTheme
@@ -21,7 +21,7 @@ API Used to configure the app theme, and enumerate options
Implemented type: [AppThemeApi](./AppThemeApi.md)
ApiRef:
-[appThemeApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/AppThemeApi.ts#L74)
+[appThemeApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/AppThemeApi.ts#L80)
### auth0Auth
@@ -32,7 +32,7 @@ Implemented types: [OpenIdConnectApi](./OpenIdConnectApi.md),
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
ApiRef:
-[auth0AuthApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L275)
+[auth0AuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L275)
### config
@@ -41,7 +41,7 @@ Used to access runtime configuration
Implemented type: [Config](./Config.md)
ApiRef:
-[configApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/ConfigApi.ts#L22)
+[configApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/ConfigApi.ts#L22)
### discovery
@@ -50,7 +50,7 @@ Provides service discovery of backend plugins
Implemented type: [DiscoveryApi](./DiscoveryApi.md)
ApiRef:
-[discoveryApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L44)
+[discoveryApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L44)
### error
@@ -59,7 +59,7 @@ Used to report errors and forward them to the app
Implemented type: [ErrorApi](./ErrorApi.md)
ApiRef:
-[errorApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/ErrorApi.ts#L65)
+[errorApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/ErrorApi.ts#L65)
### featureFlags
@@ -68,7 +68,7 @@ Used to toggle functionality in features across Backstage
Implemented type: [FeatureFlagsApi](./FeatureFlagsApi.md)
ApiRef:
-[featureFlagsApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L58)
+[featureFlagsApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L83)
### githubAuth
@@ -79,7 +79,7 @@ Implemented types: [OAuthApi](./OAuthApi.md),
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
ApiRef:
-[githubAuthApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L232)
+[githubAuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L232)
### gitlabAuth
@@ -90,7 +90,7 @@ Implemented types: [OAuthApi](./OAuthApi.md),
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
ApiRef:
-[gitlabAuthApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L262)
+[gitlabAuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L262)
### googleAuth
@@ -102,7 +102,7 @@ Implemented types: [OAuthApi](./OAuthApi.md),
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
ApiRef:
-[googleAuthApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L215)
+[googleAuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L215)
### identity
@@ -111,7 +111,7 @@ Provides access to the identity of the signed in user
Implemented type: [IdentityApi](./IdentityApi.md)
ApiRef:
-[identityApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/IdentityApi.ts#L54)
+[identityApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/IdentityApi.ts#L54)
### microsoftAuth
@@ -123,7 +123,7 @@ Implemented types: [OAuthApi](./OAuthApi.md),
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
ApiRef:
-[microsoftAuthApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L289)
+[microsoftAuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L289)
### oauth2
@@ -135,7 +135,7 @@ Implemented types: [OAuthApi](./OAuthApi.md),
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
ApiRef:
-[oauth2ApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L303)
+[oauth2ApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L303)
### oauthRequest
@@ -144,7 +144,7 @@ An API for implementing unified OAuth flows in Backstage
Implemented type: [OAuthRequestApi](./OAuthRequestApi.md)
ApiRef:
-[oauthRequestApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L130)
+[oauthRequestApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L130)
### oktaAuth
@@ -156,7 +156,17 @@ Implemented types: [OAuthApi](./OAuthApi.md),
[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
ApiRef:
-[oktaAuthApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L245)
+[oktaAuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L245)
+
+### samlAuth
+
+Example of how to use SAML custom provider
+
+Implemented types: [ProfileInfoApi](./ProfileInfoApi.md),
+[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md)
+
+ApiRef:
+[samlAuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L317)
### storage
@@ -165,4 +175,4 @@ Provides the ability to store data which is unique to the user
Implemented type: [StorageApi](./StorageApi.md)
ApiRef:
-[storageApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/StorageApi.ts#L68)
+[storageApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/StorageApi.ts#L68)
diff --git a/docs/reference/utility-apis/SessionApi.md b/docs/reference/utility-apis/SessionApi.md
index e7a9e58c59..7d271558d6 100644
--- a/docs/reference/utility-apis/SessionApi.md
+++ b/docs/reference/utility-apis/SessionApi.md
@@ -1,7 +1,7 @@
# SessionApi
The SessionApi type is defined at
-[packages/core-api/src/apis/definitions/auth.ts:190](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L190).
+[packages/core-api/src/apis/definitions/auth.ts:190](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L190).
The following Utility APIs implement this type:
@@ -19,6 +19,8 @@ The following Utility APIs implement this type:
- [oktaAuthApiRef](./README.md#oktaauth)
+- [samlAuthApiRef](./README.md#samlauth)
+
## Members
### signIn()
@@ -75,13 +77,13 @@ export type Observable<T> = {
Defined at
-[packages/core-api/src/types.ts:53](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L53).
+[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L53).
Referenced by: [sessionState\$](#sessionstate).
### Observer
-This file contains non-react related core types used through Backstage.
+This file contains non-react related core types used throughout Backstage.
Observer interface for consuming an Observer, see TC39.
@@ -94,7 +96,7 @@ export type Observer<T> = {
Defined at
-[packages/core-api/src/types.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L24).
+[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L24).
Referenced by: [Observable](#observable).
@@ -110,7 +112,7 @@ export enum SessionState {
Defined at
-[packages/core-api/src/apis/definitions/auth.ts:182](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L182).
+[packages/core-api/src/apis/definitions/auth.ts:182](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L182).
Referenced by: [sessionState\$](#sessionstate).
@@ -133,6 +135,6 @@ export type Subscription = {
Defined at
-[packages/core-api/src/types.ts:33](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L33).
+[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L33).
Referenced by: [Observable](#observable).
diff --git a/docs/reference/utility-apis/SessionStateApi.md b/docs/reference/utility-apis/SessionStateApi.md
index 81f25aa349..a8a4c3bc3d 100644
--- a/docs/reference/utility-apis/SessionStateApi.md
+++ b/docs/reference/utility-apis/SessionStateApi.md
@@ -1,7 +1,7 @@
# SessionStateApi
The SessionStateApi type is defined at
-[packages/core-api/src/apis/definitions/auth.ts:201](https://github.com/spotify/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L201).
+[packages/core-api/src/apis/definitions/auth.ts:201](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L201).
The following Utility APIs implement this type:
@@ -56,7 +56,7 @@ export type Observable<T> = {
Defined at
-[packages/core-api/src/types.ts:53](https://github.com/spotify/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L53).
+[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L53).
Referenced by: [sessionState\$](#sessionstate).
@@ -75,7 +75,7 @@ export type Observer<T> = {
Defined at
-[packages/core-api/src/types.ts:24](https://github.com/spotify/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L24).
+[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L24).
Referenced by: [Observable](#observable).
@@ -91,7 +91,7 @@ export enum SessionState {
Defined at
-[packages/core-api/src/apis/definitions/auth.ts:192](https://github.com/spotify/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L192).
+[packages/core-api/src/apis/definitions/auth.ts:192](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L192).
Referenced by: [sessionState\$](#sessionstate).
@@ -114,6 +114,6 @@ export type Subscription = {
Defined at
-[packages/core-api/src/types.ts:33](https://github.com/spotify/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L33).
+[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L33).
Referenced by: [Observable](#observable).
diff --git a/docs/reference/utility-apis/StorageApi.md b/docs/reference/utility-apis/StorageApi.md
index e7d5131ff9..6c5595d3d8 100644
--- a/docs/reference/utility-apis/StorageApi.md
+++ b/docs/reference/utility-apis/StorageApi.md
@@ -1,7 +1,7 @@
# StorageApi
The StorageApi type is defined at
-[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/StorageApi.ts#L31).
+[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/StorageApi.ts#L31).
The following Utility API implements this type:
[storageApiRef](./README.md#storage)
@@ -79,13 +79,13 @@ export type Observable<T> = {
Defined at
-[packages/core-api/src/types.ts:53](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L53).
+[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L53).
Referenced by: [observe\$](#observe), [StorageApi](#storageapi).
### Observer
-This file contains non-react related core types used through Backstage.
+This file contains non-react related core types used throughout Backstage.
Observer interface for consuming an Observer, see TC39.
@@ -98,7 +98,7 @@ export type Observer<T> = {
Defined at
-[packages/core-api/src/types.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L24).
+[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L24).
Referenced by: [Observable](#observable).
@@ -144,7 +144,7 @@ export interface StorageApi {
Defined at
-[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/StorageApi.ts#L31).
+[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/StorageApi.ts#L31).
Referenced by: [forBucket](#forbucket).
@@ -158,7 +158,7 @@ export type StorageValueChange<T = any> = {
Defined at
-[packages/core-api/src/apis/definitions/StorageApi.ts:21](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/StorageApi.ts#L21).
+[packages/core-api/src/apis/definitions/StorageApi.ts:21](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/StorageApi.ts#L21).
Referenced by: [observe\$](#observe), [StorageApi](#storageapi).
@@ -181,6 +181,6 @@ export type Subscription = {
Defined at
-[packages/core-api/src/types.ts:33](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L33).
+[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L33).
Referenced by: [Observable](#observable).
diff --git a/docs/support/project-structure.md b/docs/support/project-structure.md
index 9720c4db3e..a30288e85e 100644
--- a/docs/support/project-structure.md
+++ b/docs/support/project-structure.md
@@ -15,48 +15,48 @@ In the project root, there are a set of files and folders which are not part of
the project as such, and may or may not be familiar to someone looking through
the code.
-- [`.changeset/`](https://github.com/spotify/backstage/tree/master/.changeset) -
+- [`.changeset/`](https://github.com/backstage/backstage/tree/master/.changeset) -
This folder contains files outlining which changes occurred in the project
since the last release. These files are added manually, but managed by
[changesets](https://github.com/atlassian/changesets) and will be removed at
every new release. They are essentially building-blocks of a CHANGELOG.
-- [`.github/`](https://github.com/spotify/backstage/tree/master/.github) -
+- [`.github/`](https://github.com/backstage/backstage/tree/master/.github) -
Standard GitHub folder. It contains - amongst other things - our workflow
definitions and templates. Worth noting is the
- [styles](https://github.com/spotify/backstage/tree/master/.github/styles)
+ [styles](https://github.com/backstage/backstage/tree/master/.github/styles)
folder which is used for a markdown spellchecker.
-- [`.yarn/`](https://github.com/spotify/backstage/tree/master/.yarn) - Backstage
- ships with it's own `yarn` implementation. This allows us to have better
- control over our `yarn.lock` file and hopefully avoid problems due to yarn
- versioning differences.
+- [`.yarn/`](https://github.com/backstage/backstage/tree/master/.yarn) -
+ Backstage ships with it's own `yarn` implementation. This allows us to have
+ better control over our `yarn.lock` file and hopefully avoid problems due to
+ yarn versioning differences.
-- [`docker/`](https://github.com/spotify/backstage/tree/master/docker) - Files
+- [`docker/`](https://github.com/backstage/backstage/tree/master/docker) - Files
related to our root Dockerfile. We are planning to refactor this, so expect
this folder to be moved in the future.
-- [`contrib/`](https://github.com/spotify/backstage/tree/master/contrib) -
+- [`contrib/`](https://github.com/backstage/backstage/tree/master/contrib) -
Collection of examples or resources provided by the community. We really
appreciate contributions in here and encourage them being kept up to date.
-- [`docs/`](https://github.com/spotify/backstage/tree/master/docs) - This is
- where we keep all of our documentation Markdown files. These ends up on
- http://backstage.io/docs. Just keep in mind that changes to the
- [`sidebars.json`](https://github.com/spotify/backstage/blob/master/microsite/sidebars.json)
+- [`docs/`](https://github.com/backstage/backstage/tree/master/docs) - This is
+ where we keep all of our documentation Markdown files. These end up on
+ https://backstage.io/docs. Just keep in mind that changes to the
+ [`sidebars.json`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.json)
file may be needed as sections are added/removed.
-- [`.editorconfig`](https://github.com/spotify/backstage/tree/master/.editorconfig) -
+- [`.editorconfig`](https://github.com/backstage/backstage/tree/master/.editorconfig) -
A configuration file used by most common code editors.
-- [`.imgbotconfig`](https://github.com/spotify/backstage/tree/master/.imgbotconfig) -
+- [`.imgbotconfig`](https://github.com/backstage/backstage/tree/master/.imgbotconfig) -
Configuration for a [bot](https://imgbot.net/)
## Monorepo packages
Every folder in both `packages/` and `plugins/` is within our monorepo setup, as
defined in
-[`package.json`](https://github.com/spotify/backstage/blob/master/package.json):
+[`package.json`](https://github.com/backstage/backstage/blob/master/package.json):
```json
"workspaces": {
@@ -74,30 +74,36 @@ Let's look at them individually.
These are all the packages that we use within the project. [Plugins](#plugins)
are separated out into their own folder, see further down.
-- [`app/`](https://github.com/spotify/backstage/tree/master/packages/app) - This
- is our take on how an App could look like, bringing together a set of packages
- and plugins into a working Backstage App. This is not a published package, and
- the main goals are to provide a demo of what an App could look like and to
- enable local development.
+- [`app/`](https://github.com/backstage/backstage/tree/master/packages/app) -
+ This is our take on how an App could look like, bringing together a set of
+ packages and plugins into a working Backstage App. This is not a published
+ package, and the main goals are to provide a demo of what an App could look
+ like and to enable local development.
-- [`backend/`](https://github.com/spotify/backstage/tree/master/packages/backend) -
+- [`backend/`](https://github.com/backstage/backstage/tree/master/packages/backend) -
Every standalone Backstage project will have both an `app` _and_ a `backend`
package. The `backend` uses plugins to construct a working backend that the
frontend (`app`) can use.
-- [`backend-common/`](https://github.com/spotify/backstage/tree/master/packages/backend-common) -
+- [`backend-common/`](https://github.com/backstage/backstage/tree/master/packages/backend-common) -
There are no "core" packages in the backend. Instead we have `backend-common`
which contains helper middleware and other utils.
-- [`catalog-model/`](https://github.com/spotify/backstage/tree/master/packages/catalog-model) -
+- [`catalog-client`](https://github.com/backstage/backstage/tree/master/packages/catalog-client) -
+ An isomorphic client to interact with the Software Catalog. Backend plugins
+ can use the package directly. Frontend plugins can use the client by using
+ `@backstage/plugin-catalog` in combination with `useApi` and the
+ `catalogApiRef`.
+
+- [`catalog-model/`](https://github.com/backstage/backstage/tree/master/packages/catalog-model) -
You can consider this to be a library for working with the catalog of sorts.
It contains the definition of an
[Entity](https://backstage.io/docs/features/software-catalog/references#docsNav),
as well as validation and other logic related to it. This package can be used
in both the frontend and the backend.
-- [`cli/`](https://github.com/spotify/backstage/tree/master/packages/cli) - One
- of the biggest packages in our project, the `cli` is used to build, serve,
+- [`cli/`](https://github.com/backstage/backstage/tree/master/packages/cli) -
+ One of the biggest packages in our project, the `cli` is used to build, serve,
diff, create-plugins and more. In the early days of this project, we started
out with calling tools directly - such as `eslint` - through `package.json`.
But as it was tricky to have a good development experience around that when we
@@ -105,86 +111,89 @@ are separated out into their own folder, see further down.
everything looks the same in `package.json`. Much like
[react-scripts](https://github.com/facebook/create-react-app/tree/master/packages/react-scripts).
-- [`cli-common/`](https://github.com/spotify/backstage/tree/master/packages/cli-common) -
+- [`cli-common/`](https://github.com/backstage/backstage/tree/master/packages/cli-common) -
This package mainly handles path resolving. It is a separate package to reduce
- bugs in [cli](https://github.com/spotify/backstage/tree/master/packages/cli).
- We also want as few dependencies as possible to reduce download time when
- running the cli which is another reason this is a separate package.
+ bugs in
+ [cli](https://github.com/backstage/backstage/tree/master/packages/cli). We
+ also want as few dependencies as possible to reduce download time when running
+ the cli which is another reason this is a separate package.
-- [`config/`](https://github.com/spotify/backstage/tree/master/packages/config) -
+- [`config/`](https://github.com/backstage/backstage/tree/master/packages/config) -
The way we read configuration data. This package can take a bunch of config
objects and merge them together.
- [app-config.yaml](https://github.com/spotify/backstage/blob/master/app-config.yaml)
+ [app-config.yaml](https://github.com/backstage/backstage/blob/master/app-config.yaml)
is an example of an config object.
-- [`config-loader/`](https://github.com/spotify/backstage/tree/master/packages/config-loader) -
+- [`config-loader/`](https://github.com/backstage/backstage/tree/master/packages/config-loader) -
This package is used to read config objects. It does not know how to merge,
but only reads files and passes them on to the config. As this part is only
used by the backend, we chose to separate `config` and `config-loader` into
two different packages.
-- [`core/`](https://github.com/spotify/backstage/tree/master/packages/core) -
+- [`core/`](https://github.com/backstage/backstage/tree/master/packages/core) -
This package contains our visual React components, some of which you can find
in
[plugin examples](https://backstage.io/storybook/?path=/story/plugins-examples--plugin-with-data).
Apart from that it re-exports everything from [`core-api`] so that users only
need to rely on one package.
-- [`core-api/`](https://github.com/spotify/backstage/tree/master/packages/core-api) -
+- [`core-api/`](https://github.com/backstage/backstage/tree/master/packages/core-api) -
This package contains APIs and definitions of such. It is it's own package
because we needed to split our `test-utils` package. It's an implementation
detail that we try to hide from our users, and no one should have to depend on
it directly.
-- [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils) -
+- [`test-utils/`](https://github.com/backstage/backstage/tree/master/packages/test-utils) -
This package contains specific testing facilities used when testing
`core-api`.
-- [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core) -
+- [`test-utils-core/`](https://github.com/backstage/backstage/tree/master/packages/test-utils-core) -
This package contains more general purpose testing facilities for testing a
Backstage App.
-- [`create-app/`](https://github.com/spotify/backstage/tree/master/packages/create-app) -
+- [`create-app/`](https://github.com/backstage/backstage/tree/master/packages/create-app) -
An CLI to specifically scaffold a new Backstage App. It does so by using a
- [template](https://github.com/spotify/backstage/tree/master/packages/create-app/templates/default-app).
+ [template](https://github.com/backstage/backstage/tree/master/packages/create-app/templates/default-app).
-- [`dev-utils/`](https://github.com/spotify/backstage/tree/master/packages/dev-utils) -
+- [`dev-utils/`](https://github.com/backstage/backstage/tree/master/packages/dev-utils) -
Helps you setup a plugin for isolated development so that it can be served
separately.
-- [`docgen/`](https://github.com/spotify/backstage/tree/master/packages/docgen) -
+- [`docgen/`](https://github.com/backstage/backstage/tree/master/packages/docgen) -
Uses the
- [Typescript Compiler API](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API)
+ [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API)
to read out definitions and generate documentation for it.
-- [`e2e-test/`](https://github.com/spotify/backstage/tree/master/packages/e2e-test) -
+- [`e2e-test/`](https://github.com/backstage/backstage/tree/master/packages/e2e-test) -
Another CLI that can be run to try out what would happen if you built all the
packages, publish them, created a new app, and the run it. CI uses this for
e2e-tests.
-- [`storybook/`](https://github.com/spotify/backstage/tree/master/packages/storybook) -
+- [`integration/`](https://github.com/backstage/backstage/tree/master/packages/integration) -
+ Common functionalities of integrations like GitHub, GitLab, etc.
+
+- [`storybook/`](https://github.com/backstage/backstage/tree/master/packages/storybook) -
This folder contains only the storybook config. Stories are within the core
package. The Backstage Storybook is found
[here](https://backstage.io/storybook)
-- [`techdocs-cli/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-cli) -
- Used for verifying TechDocs locally.
+- [`techdocs-common/`](https://github.com/backstage/backstage/tree/master/packages/techdocs-common) -
+ Common functionalities for TechDocs, to be shared between
+ [techdocs-backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend)
+ plugin and [techdocs-cli](https://github.com/backstage/techdocs-cli).
-- [`techdocs-container/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-container) -
- Used by the `techdocs-cli`
+- [`test-utils-core/`](https://github.com/backstage/backstage/tree/master/packages/test-utils-core)
-- [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core)
+- [`test-utils/`](https://github.com/backstage/backstage/tree/master/packages/test-utils)
-- [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils)
-
-- [`theme/`](https://github.com/spotify/backstage/tree/master/packages/theme) -
+- [`theme/`](https://github.com/backstage/backstage/tree/master/packages/theme) -
Holds the Backstage Theme.
### `plugins/`
Most of the functionality of a Backstage App comes from plugins. Even core
features can be plugins, take the
-[catalog](https://github.com/spotify/backstage/tree/master/plugins/catalog) as
+[catalog](https://github.com/backstage/backstage/tree/master/plugins/catalog) as
an example.
We can categorize plugins into three different types; **Frontend**, **Backend**
@@ -196,18 +205,18 @@ reason is for clear separation of concerns.
Take a look at our [Plugin Gallery](https://backstage.io/plugins) or browse
through the
-[`plugins/`](https://github.com/spotify/backstage/tree/master/plugins) folder.
+[`plugins/`](https://github.com/backstage/backstage/tree/master/plugins) folder.
## Packages outside of the monorepo
For convenience we include packages in our project that are not part of our
monorepo setup.
-- [`microsite/`](https://github.com/spotify/backstage/blob/master/microsite) -
+- [`microsite/`](https://github.com/backstage/backstage/blob/master/microsite) -
This folder contains the source code for backstage.io. It is built with
[Docusaurus](https://docusaurus.io/). This folder is not part of the monorepo
due to dependency reasons. Look at the
- [README](https://github.com/spotify/backstage/blob/master/microsite/README.md)
+ [README](https://github.com/backstage/backstage/blob/master/microsite/README.md)
for instructions on how to run it locally.
## Root files specifically used by the `app`
@@ -216,22 +225,22 @@ These files are kept in the root of the project mostly by historical reasons.
Some of these files may be subject to be moved out of the root sometime in the
future.
-- [`.npmrc`](https://github.com/spotify/backstage/tree/master/.npmrc) - It's
+- [`.npmrc`](https://github.com/backstage/backstage/tree/master/.npmrc) - It's
common for companies to have their own npm registry, this files makes sure
that this folder use the public registry.
-- [`.vale.ini`](https://github.com/spotify/backstage/tree/master/.vale.ini) -
+- [`.vale.ini`](https://github.com/backstage/backstage/tree/master/.vale.ini) -
[Spell checker](https://github.com/errata-ai/vale) for Markdown files.
-- [`.yarnrc`](https://github.com/spotify/backstage/tree/master/.yarnrc) -
+- [`.yarnrc`](https://github.com/backstage/backstage/tree/master/.yarnrc) -
Enforces "our" version of Yarn.
-- [`app-config.yaml`](https://github.com/spotify/backstage/tree/master/app-config.yaml) -
+- [`app-config.yaml`](https://github.com/backstage/backstage/tree/master/app-config.yaml) -
Configuration for the app, both frontend and backend.
-- [`catalog-info.yaml`](https://github.com/spotify/backstage/tree/master/catalog-info.yaml) -
+- [`catalog-info.yaml`](https://github.com/backstage/backstage/tree/master/catalog-info.yaml) -
Description of Backstage in the Backstage Entity format.
-- [`lerna.json`](https://github.com/spotify/backstage/tree/master/lerna.json) -
+- [`lerna.json`](https://github.com/backstage/backstage/tree/master/lerna.json) -
[Lerna](https://github.com/lerna/lerna) monorepo config. We are using
`yarn workspaces`, so this will only be used for executing scripts.
diff --git a/docs/support/support.md b/docs/support/support.md
index 12bc7cfaf9..49075366af 100644
--- a/docs/support/support.md
+++ b/docs/support/support.md
@@ -5,15 +5,16 @@ description: Support and Community Details and Links
---
- [Discord chatroom](https://discord.gg/MUpMjP2) - Get support or discuss the
- project
-- [Good First Issues](https://github.com/spotify/backstage/contribute) - Start
- here if you want to contribute
-- [RFCs](https://github.com/spotify/backstage/labels/rfc) - Help shape the
- technical direction
-- [FAQ](../FAQ.md) - Frequently Asked Questions
-- [Code of Conduct](../../CODE_OF_CONDUCT.md) - This is how we roll
-- [Blog](https://backstage.io/blog/) - Announcements and updates
+ project.
+- [Good First Issues](https://github.com/backstage/backstage/contribute) - Start
+ here if you want to contribute.
+- [RFCs](https://github.com/backstage/backstage/labels/rfc) - Help shape the
+ technical direction by reviewing _Request for Comments_ issues.
+- [FAQ](../FAQ.md) - Frequently Asked Questions.
+- [Code of Conduct](https://github.com/backstage/backstage/blob/master/CODE_OF_CONDUCT.md) -
+ This is how we roll.
+- [Blog](https://backstage.io/blog/) - Announcements and updates.
- [Newsletter](https://mailchi.mp/spotify/backstage-community) - Subscribe to
- our email newsletter
+ our email newsletter.
- Give us a star ⭐️ - If you are using Backstage or think it is an interesting
- project, we would love a star ❤️
+ project, we would love a star! ❤️
diff --git a/docs/tutorials/journey.md b/docs/tutorials/journey.md
index 7627920a75..adefdfa73f 100644
--- a/docs/tutorials/journey.md
+++ b/docs/tutorials/journey.md
@@ -22,7 +22,7 @@ music and wants to have a theme tune for every service in Backstage.
Sam built a Spotify plugin for Backstage that allows service owners to define a
theme tune for their service. The theme tune plays whenever a user visits the
-service page in Backstage. The plugin is published to NPM and available for any
+service page in Backstage. The plugin is published to npm and available for any
organization to easily install and add to their Backstage installation.
# 1. A New Plugin
@@ -264,14 +264,9 @@ release of Sam's plugin specifies a dependency on Backstage with a minimum
version set to the same release as the one were the annotation was added to the
core schema.
-
-
diff --git a/docs/tutorials/quickstart-app-plugin.md b/docs/tutorials/quickstart-app-plugin.md
index daf76aa1cd..0f8d9bb84b 100644
--- a/docs/tutorials/quickstart-app-plugin.md
+++ b/docs/tutorials/quickstart-app-plugin.md
@@ -81,13 +81,13 @@ import { useApi } from '@backstage/core-api';
_from inline:_
```tsx
-const ExampleComponent: FC<{}> = () => ( ... )
+const ExampleComponent = () => ( ... )
```
_to block:_
```tsx
-const ExampleComponent: FC<{}> = () => {
+const ExampleComponent = () => {
return (
...
@@ -120,10 +120,10 @@ If everything is saved, you should see your name, id, and email on the
github-playground page. Our data accessed is synchronous. So we just grab and
go.
-https://github.com/spotify/backstage/tree/master/contrib
+https://github.com/backstage/backstage/tree/master/contrib
6. Here is the entire file for reference
- [ExampleComponent.tsx](https://github.com/spotify/backstage/tree/master/contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md)
+ [ExampleComponent.tsx](https://github.com/backstage/backstage/tree/master/contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md)
# The Wipe
@@ -135,7 +135,7 @@ changes, let's start by wiping this component clean.
1. Replace everything in the file with the following:
```tsx
-import React, { FC } from 'react';
+import React from 'react';
import { useAsync } from 'react-use';
import Alert from '@material-ui/lab/Alert';
import {
@@ -147,7 +147,7 @@ import {
import { useApi } from '@backstage/core-api';
import { graphql } from '@octokit/graphql';
-const ExampleFetchComponent: FC<{}> = () => {
+const ExampleFetchComponent = () => {
return - # 9. Revenge of the Sam Sam, now in full control of all theme tunes in Backstage, releases v2.0.1, which switches all tracks to 4uLU6hMCjMI75M1A2tKUQC. Sam wanted to do something more nefarious, but since Backstage sandboxes sensitive actions and is mostly read-only with strict CSP, Sam's hands were tied. - -
Nothing to see yet
;
};
@@ -223,7 +223,7 @@ type DenseTableProps = {
viewer: Viewer;
};
-export const DenseTable: FC
`
diff --git a/microsite/blog/2020-03-16-announcing-backstage.md b/microsite/blog/2020-03-16-announcing-backstage.md
index 3911debf08..5094de7b37 100644
--- a/microsite/blog/2020-03-16-announcing-backstage.md
+++ b/microsite/blog/2020-03-16-announcing-backstage.md
@@ -1,6 +1,6 @@
---
title: Announcing Backstage
-author: Stefan Ålund
+author: Stefan Ålund, Spotify
authorURL: http://twitter.com/stalund
authorImageURL: https://pbs.twimg.com/profile_images/121166861/6919c047c0d0edaace78c3009b28e917-user-full-200-130.generated_400x400.jpg
---
@@ -41,4 +41,4 @@ We are envisioning three phases of the project and we have already begun work on
- **Phase 3:** Ecosystem (later) - Everyone's infrastructure stack is different. By fostering a vibrant community of contributors we hope to provide an ecosystem of Open Source plugins/integrations that allows you to pick the tools that match your stack.
-Our vision for Backstage is for it to become the trusted standard toolbox (read: UI layer) for the open source infrastructure landscape. Think of it like Kubernetes for developer experience. We realize this is an ambitious goal. We can’t do it alone. If this sounds interesting or you'd like to help us shape our product vision, we'd love to talk. You can email me directly: [alund@spotify.com](mailto:alund@spotify.com).
+Our vision for Backstage is for it to become the trusted standard toolbox (read: UI layer) for the open source infrastructure landscape. Think of it like Kubernetes for developer experience. We realize this is an ambitious goal. We can’t do it alone. If this sounds interesting or you'd like to help us shape our product vision, we'd love to talk. You can email us directly: [backstage-interest@spotify.com](mailto:backstage-interest@spotify.com).
diff --git a/microsite/blog/2020-03-18-what-is-backstage.md b/microsite/blog/2020-03-18-what-is-backstage.md
index 8b0a0fcbe6..2c2b81d64d 100644
--- a/microsite/blog/2020-03-18-what-is-backstage.md
+++ b/microsite/blog/2020-03-18-what-is-backstage.md
@@ -1,6 +1,6 @@
---
title: What the heck is Backstage anyway?
-author: Stefan Ålund
+author: Stefan Ålund, Spotify
authorURL: http://twitter.com/stalund
authorImageURL: https://pbs.twimg.com/profile_images/121166861/6919c047c0d0edaace78c3009b28e917-user-full-200-130.generated_400x400.jpg
---
@@ -81,8 +81,8 @@ Similar to how Backstage ties together all of Spotify’s infrastructure, our am
## What’s next?
-We are envisioning [three phases](https://github.com/spotify/backstage/milestones) of the project (so far), and we have already begun work on various aspects of these phases. The best way to track the work and see where you can jump in and help out is:
+We are envisioning [three phases](https://github.com/backstage/backstage/milestones) of the project (so far), and we have already begun work on various aspects of these phases. The best way to track the work and see where you can jump in and help out is:
-https://github.com/spotify/backstage/milestones
+https://github.com/backstage/backstage/milestones
-Want to discuss the project or need support? Join us on [Discord](https://discord.gg/MUpMjP2) or reach out on [alund@spotify.com](mailto:alund@spotify.com).
+Want to discuss the project or need support? Join us on [Discord](https://discord.gg/MUpMjP2) or reach out on [backstage-interest@spotify.com](mailto:backstage-interest@spotify.com).
diff --git a/microsite/blog/2020-04-06-lighthouse-plugin.md b/microsite/blog/2020-04-06-lighthouse-plugin.md
index 2d5c7b96b7..dcdb4b78e5 100644
--- a/microsite/blog/2020-04-06-lighthouse-plugin.md
+++ b/microsite/blog/2020-04-06-lighthouse-plugin.md
@@ -1,6 +1,6 @@
---
title: Introducing Lighthouse for Backstage
-author: Paul Marbach
+author: Paul Marbach, Spotify
authorURL: http://twitter.com/fastfrwrd
authorImageURL: https://pbs.twimg.com/profile_images/1224058798958088192/JPxS8uzR_400x400.jpg
---
@@ -33,7 +33,7 @@ Trigger an audit directly from Backstage, or trigger audits programmatically wit
## Using Lighthouse in Backstage
-To learn how you can enable Lighthouse auditing within Backstage, head over to the [README](https://github.com/spotify/backstage/tree/master/plugins/lighthouse) for the plugin to get started.
+To learn how you can enable Lighthouse auditing within Backstage, head over to the [README](https://github.com/backstage/backstage/tree/master/plugins/lighthouse) for the plugin to get started.
## A personal note
diff --git a/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md b/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md
index dff567eaf3..65102c919f 100644
--- a/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md
+++ b/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md
@@ -1,6 +1,6 @@
---
title: How to quickly set up Backstage
-author: Marcus Eide
+author: Marcus Eide, Spotify
authorURL: https://github.com/marcuseide
authorImageURL: https://secure.gravatar.com/avatar/20223f1e03673c7c1e6282fbebaf6942
---
@@ -132,4 +132,4 @@ If you are developing a plugin that might be useful for others, consider releasi
## Ready to get started?
-Head over to GitHub and check out the [project](https://github.com/spotify/backstage) or download our [CLI](https://www.npmjs.com/package/@backstage/cli). If you have more questions, join us on [Discord](https://discord.gg/MUpMjP2) or [create an issue](https://github.com/spotify/backstage/issues/new/choose).
+Head over to GitHub and check out the [project](https://github.com/backstage/backstage) or download our [CLI](https://www.npmjs.com/package/@backstage/cli). If you have more questions, join us on [Discord](https://discord.gg/MUpMjP2) or [create an issue](https://github.com/backstage/backstage/issues/new/choose).
diff --git a/microsite/blog/2020-05-14-tech-radar-plugin.md b/microsite/blog/2020-05-14-tech-radar-plugin.md
index d78d5d67fa..b78cf9004f 100644
--- a/microsite/blog/2020-05-14-tech-radar-plugin.md
+++ b/microsite/blog/2020-05-14-tech-radar-plugin.md
@@ -1,6 +1,6 @@
---
title: Introducing Tech Radar for Backstage
-author: Bilawal Hameed
+author: Bilawal Hameed, Spotify
authorURL: http://twitter.com/bilawalhameed
authorImageURL: https://avatars0.githubusercontent.com/bih
---
@@ -34,11 +34,11 @@ To learn about how you can bring the Tech Radar to your Backstage installation,
I want to thank both the Backstage team and Spotify. Firstly, I’ve been working with our internal version of Backstage for over a year, and the developer experience since open sourcing has been even more of a joy to work with. Secondly, the 10% hack time that Spotify generously provides to all engineers enabled me to open source the Tech Radar plugin.
-Since open sourcing it, the community has shown great interest in yet another powerful use case of Backstage. There was also an enthusiastic open source contributor who volunteered to migrate the plugin to TypeScript and React Hooks [in just 29 minutes](https://github.com/spotify/backstage/issues/661) of opening the issue!
+Since open sourcing it, the community has shown great interest in yet another powerful use case of Backstage. There was also an enthusiastic open source contributor who volunteered to migrate the plugin to TypeScript and React Hooks [in just 29 minutes](https://github.com/backstage/backstage/issues/661) of opening the issue!
I can’t wait to see how others benefit from the Tech Radar in their organizations!
[lighthouse website audits]: https://backstage.io/blog/2020/04/06/lighthouse-plugin
-[tech radar plugin]: https://github.com/spotify/backstage/tree/master/plugins/tech-radar
+[tech radar plugin]: https://github.com/backstage/backstage/tree/master/plugins/tech-radar
[thoughtworks]: https://www.thoughtworks.com/radar
[zalando]: https://opensource.zalando.com/tech-radar/
diff --git a/microsite/blog/2020-05-14-weaveworks-covid-19-app-uses-backstage-ui.md b/microsite/blog/2020-05-14-weaveworks-covid-19-app-uses-backstage-ui.md
index 68e3f903c7..3e3d8a537a 100644
--- a/microsite/blog/2020-05-14-weaveworks-covid-19-app-uses-backstage-ui.md
+++ b/microsite/blog/2020-05-14-weaveworks-covid-19-app-uses-backstage-ui.md
@@ -1,6 +1,6 @@
---
title: Weaveworks’ COVID-19 app uses Backstage UI
-author: Jeff Feng
+author: Jeff Feng, Spotify
authorURL: https://github.com/fengypants
authorImageURL: https://avatars2.githubusercontent.com/u/46946747
---
diff --git a/microsite/blog/2020-05-22-phase-2-service-catalog.md b/microsite/blog/2020-05-22-phase-2-service-catalog.md
index 682965d2dd..520a2a5f10 100644
--- a/microsite/blog/2020-05-22-phase-2-service-catalog.md
+++ b/microsite/blog/2020-05-22-phase-2-service-catalog.md
@@ -1,13 +1,13 @@
---
title: Starting Phase 2: The Service Catalog
-author: Stefan Ålund
+author: Stefan Ålund, Spotify
authorURL: http://twitter.com/stalund
authorImageURL: https://pbs.twimg.com/profile_images/121166861/6919c047c0d0edaace78c3009b28e917-user-full-200-130.generated_400x400.jpg
---
**TL;DR** Thanks to the help from the Backstage community, we’ve made excellent progress and are now moving into Phase 2 of Backstage — building out a Service Catalog and the surrounding systems that will help unify the tools you use to manage your software.
-We released the open source version of Backstage a little less than two months ago, and have been thrilled to see so many people jumping in and contributing to the project in its early stages. We’re excited to see what the community can build together as we progress through [each phase of Backstage](https://github.com/spotify/backstage#project-roadmap).
+We released the open source version of Backstage a little less than two months ago, and have been thrilled to see so many people jumping in and contributing to the project in its early stages. We’re excited to see what the community can build together as we progress through [each phase of Backstage](https://github.com/backstage/backstage#project-roadmap).
@@ -15,7 +15,7 @@ We released the open source version of Backstage a little less than two months a
## Progress so far
-Phase 1 was all about building an extensible frontend platform, enabling teams to start creating a single, consistent UI layer for your internal infrastructure and tools in the form of [plugins](https://github.com/spotify/backstage/labels/plugin). In fact, thanks to our amazing (30+) [contributors](https://github.com/spotify/backstage/graphs/contributors), we were able to complete most of Phase 1 earlier than expected. 🎉
+Phase 1 was all about building an extensible frontend platform, enabling teams to start creating a single, consistent UI layer for your internal infrastructure and tools in the form of [plugins](https://github.com/backstage/backstage/labels/plugin). In fact, thanks to our amazing (30+) [contributors](https://github.com/backstage/backstage/graphs/contributors), we were able to complete most of Phase 1 earlier than expected. 🎉
Today, we are happy to announce that we are shifting our focus to Phase 2!
@@ -27,7 +27,7 @@ Quote from [Platform Nuts & Bolts: Extendable Data Models](https://www.kislayver
Entities, or what we refer to as “components” in Backstage, represent all software, including services, websites, libraries, data pipelines, and so forth. The focus of Phase 2 will be on adding an entity model in Backstage that makes it easy for engineers to create and manage the software components they own.
-With the ability to create a plethora of components in Backstage, how does one keep track of all the software in the ecosystem? Therein lies the highlight feature of Phase 2: the [Service Catalog](https://github.com/spotify/backstage/milestone/4). The service catalog — or software catalog — is a centralized system that keeps track of ownership and metadata about all software in your ecosystem. The catalog is built around the concept of [metadata yaml files](/docs/architecture-decisions/adr002-default-catalog-file-format.md) stored together with the code, which are then harvested and visualized in Backstage.
+With the ability to create a plethora of components in Backstage, how does one keep track of all the software in the ecosystem? Therein lies the highlight feature of Phase 2: the [Service Catalog](https://github.com/backstage/backstage/milestone/4). The service catalog — or software catalog — is a centralized system that keeps track of ownership and metadata about all software in your ecosystem. The catalog is built around the concept of [metadata yaml files](/docs/architecture-decisions/adrs-adr002) stored together with the code, which are then harvested and visualized in Backstage.
@@ -39,13 +39,13 @@ On top of that, we have found that the service catalog is a great way to organis
-More concretely, having this structure in place will allow plugins such as [CircleCI](https://github.com/spotify/backstage/tree/master/plugins/circleci) to show only the builds for the specific service you are viewing, or a [Spinnaker](https://github.com/spotify/backstage/issues/631) plugin to show running deployments, or an Open API plugin to [show documentation](https://github.com/spotify/backstage/issues/627) for endpoints exposed by the service, or the [Lighthouse](https://github.com/spotify/backstage/tree/master/plugins/lighthouse) plugin to show audit reports for your website. You get the point.
+More concretely, having this structure in place will allow plugins such as [CircleCI](https://github.com/backstage/backstage/tree/master/plugins/circleci) to show only the builds for the specific service you are viewing, or a [Spinnaker](https://github.com/backstage/backstage/issues/631) plugin to show running deployments, or an Open API plugin to [show documentation](https://github.com/backstage/backstage/issues/627) for endpoints exposed by the service, or the [Lighthouse](https://github.com/backstage/backstage/tree/master/plugins/lighthouse) plugin to show audit reports for your website. You get the point.
## Timeline
Our estimated timeline has us delivering these pieces in increments leading up to June 22. But with the support of the community we wouldn’t be surprised if things land earlier than that. 🙏
-If you are interested in joining us, check out our [Milestones](https://github.com/spotify/backstage/milestones) and connected Issues.
+If you are interested in joining us, check out our [Milestones](https://github.com/backstage/backstage/milestones) and connected Issues.
## Long-term vision
diff --git a/microsite/blog/2020-06-22-backstage-service-catalog-alpha.md b/microsite/blog/2020-06-22-backstage-service-catalog-alpha.md
index 0928b8769b..4519f16d96 100644
--- a/microsite/blog/2020-06-22-backstage-service-catalog-alpha.md
+++ b/microsite/blog/2020-06-22-backstage-service-catalog-alpha.md
@@ -1,6 +1,6 @@
---
title: Backstage Service Catalog released in alpha
-author: Stefan Ålund
+author: Stefan Ålund, Spotify
authorURL: http://twitter.com/stalund
image: https://backstage.io/blog/assets/6/header.png
---
@@ -24,7 +24,7 @@ With these insights we decided to re-focus our efforts towards the most requeste
## What is the service catalog?
-The Backstage Service Catalog — actually, a software catalog, since it includes more than just services — is a centralized system that keeps track of ownership and metadata for all the software in your ecosystem (services, websites, libraries, data pipelines, etc). The catalog is built around the concept of [metadata yaml files](/docs/architecture-decisions/adr002-default-catalog-file-format.md#format) stored together with the code, which are then harvested and visualized in Backstage.
+The Backstage Service Catalog — actually, a software catalog, since it includes more than just services — is a centralized system that keeps track of ownership and metadata for all the software in your ecosystem (services, websites, libraries, data pipelines, etc). The catalog is built around the concept of [metadata yaml files](/docs/architecture-decisions/adrs-adr002) stored together with the code, which are then harvested and visualized in Backstage.
This was our pitch for the virtues of a service catalog when we first [announced](https://backstage.io/blog/2020/05/22/phase-2-service-catalog) it as part of Phase 2:
@@ -40,7 +40,7 @@ You’ll be able to see many of these virtues in action with this alpha release
Alpha is our shorthand for "we don’t yet think Backstage is ready for production, but we’d love for you to test it and provide us with feedback". However, you should be able to try out the functionality of the service catalog:
-1. Register software components ([examples](https://github.com/spotify/backstage/tree/master/packages/catalog-model/examples))
+1. Register software components ([examples](https://github.com/backstage/backstage/tree/master/packages/catalog-model/examples))
2. See all components represented in the catalog
3. Search across all components
4. Get an overview of the metadata of the components
@@ -49,6 +49,6 @@ Alpha is our shorthand for "we don’t yet think Backstage is ready for producti
As with most alpha releases, you should expect things to change quite a lot until we reach the beta stage (we’re targeting the end of summer). There are obviously many things missing as well, but we wanted to start collecting feedback early and make it easier to see the end-to-end flow.
-If you have feedback or questions, please open a [GitHub issue](https://github.com/spotify/backstage/issues), ping us on [Discord chat](https://discord.gg/EBHEGzX) or send me an email at [alund@spotify.com](mailto:alund@spotify.com) 🙏
+If you have feedback or questions, please open a [GitHub issue](https://github.com/backstage/backstage/issues), ping us on [Discord chat](https://discord.gg/EBHEGzX) or send us an email at [backstage-interest@spotify.com](mailto:backstage-interest@spotify.com) 🙏
To get regular product updates and news about the Backstage community, sign up for the [Backstage newsletter](https://mailchi.mp/spotify/backstage-community).
diff --git a/microsite/blog/2020-07-01-how-to-enable-authentication-in-backstage-using-passport.md b/microsite/blog/2020-07-01-how-to-enable-authentication-in-backstage-using-passport.md
index ccdd8b34c6..ce778c9dc2 100644
--- a/microsite/blog/2020-07-01-how-to-enable-authentication-in-backstage-using-passport.md
+++ b/microsite/blog/2020-07-01-how-to-enable-authentication-in-backstage-using-passport.md
@@ -1,6 +1,6 @@
---
title: How to enable authentication in Backstage using Passport
-author: Lee Mills
+author: Lee Mills, Spotify
authorURL: https://github.com/leemills83
authorImageURL: https://avatars1.githubusercontent.com/u/1236238?s=460&v=4
---
@@ -21,7 +21,7 @@ Passport has allowed us to leverage an existing open-source authentication frame
-First, check out the provided Google and GitHub implementations! [Spin up a local copy of Backstage](https://backstage.io/blog/2020/04/30/how-to-quickly-set-up-backstage) along with our example-backend. You can find more documentation on setting up the example backend [here](https://github.com/spotify/backstage/tree/master/packages/backend), but be sure to include the relevant client IDs and secrets when running `yarn start`:
+First, check out the provided Google and GitHub implementations! [Spin up a local copy of Backstage](https://backstage.io/blog/2020/04/30/how-to-quickly-set-up-backstage) along with our example-backend. You can find more documentation on setting up the example backend [here](https://github.com/backstage/backstage/tree/master/packages/backend), but be sure to include the relevant client IDs and secrets when running `yarn start`:
```
AUTH_GOOGLE_CLIENT_ID=x AUTH_GOOGLE_CLIENT_SECRET=x AUTH_GITHUB_CLIENT_ID=x AUTH_GITHUB_CLIENT_SECRET=x SENTRY_TOKEN=x LOG_LEVEL=debug yarn start
@@ -39,8 +39,8 @@ Getting started is really straightforward, and can be broadly broken down into f
4. Add the provider to the backend.
5. Add a frontend Auth Utility API.
-For full details, take a look at our [“Adding authentication providers” documentation](/docs/auth/add-auth-provider.md) and at the [excellent documentation](http://www.passportjs.org/docs/) provided by Passport.
+For full details, take a look at our [“Adding authentication providers” documentation](/docs/auth/add-auth-provider) and at the [excellent documentation](http://www.passportjs.org/docs/) provided by Passport.
## Interested in contributing to the next steps for authentication?
-We’ve already seen both GitLab and Okta contributions from the community — and we’re thinking about a few more providers we’d like to add to Backstage, too. You can find those, and other authentication-related issues, in our repository by filtering with the [auth label](https://github.com/spotify/backstage/issues?q=is%3Aissue+is%3Aopen+label%3Aauth).
+We’ve already seen both GitLab and Okta contributions from the community — and we’re thinking about a few more providers we’d like to add to Backstage, too. You can find those, and other authentication-related issues, in our repository by filtering with the [auth label](https://github.com/backstage/backstage/issues?q=is%3Aissue+is%3Aopen+label%3Aauth).
diff --git a/microsite/blog/2020-08-05-announcing-backstage-software-templates.md b/microsite/blog/2020-08-05-announcing-backstage-software-templates.md
index 81d495e1c3..afda20e499 100644
--- a/microsite/blog/2020-08-05-announcing-backstage-software-templates.md
+++ b/microsite/blog/2020-08-05-announcing-backstage-software-templates.md
@@ -1,6 +1,6 @@
---
title: Announcing Backstage Software Templates
-author: Stefan Ålund
+author: Stefan Ålund, Spotify
authorURL: https://twitter.com/stalund
---
@@ -73,6 +73,6 @@ Backstage ships with four example templates, but since these are likely not the
We have learned that one of the keys to getting these standards adopted is to keep an open process. Templates are code. By making it clear to your engineers that you are open to pull requests, and that teams with different needs can add their own templates, you are on the path of striking a good balance between autonomy and standardization.
-If you have feedback or questions, please open a [GitHub issue](https://github.com/spotify/backstage/issues), ping us on [Discord chat](https://discord.gg/EBHEGzX) or send me an email at [alund@spotify.com](mailto:alund@spotify.com) 🙏
+If you have feedback or questions, please open a [GitHub issue](https://github.com/backstage/backstage/issues), ping us on [Discord chat](https://discord.gg/EBHEGzX) or send us an email at [backstage-interest@spotify.com](mailto:backstage-interest@spotify.com) 🙏
To get regular product updates and news about the Backstage community, sign up for the [Backstage newsletter](https://mailchi.mp/spotify/backstage-community).
diff --git a/microsite/blog/2020-09-08-announcing-tech-docs.md b/microsite/blog/2020-09-08-announcing-tech-docs.md
index 48b6eeb7cc..f09c73fd83 100644
--- a/microsite/blog/2020-09-08-announcing-tech-docs.md
+++ b/microsite/blog/2020-09-08-announcing-tech-docs.md
@@ -1,6 +1,6 @@
---
title: Announcing TechDocs: Spotify’s docs-like-code plugin for Backstage
-author: Gary Niemen
+author: Gary Niemen, Spotify
authorURL: https://github.com/garyniemen
---
@@ -21,11 +21,11 @@ But this is just one way to do it. Today we’re most excited for what the open
## Okay, let’s start collaborating
-If you go to [GitHub](https://github.com/spotify/backstage/tree/master/plugins) now, you’ll find everything you need to start collaborating with us to build out the docs-like-code Backstage plugin — we’ll call it TechDocs in the open as well.
+If you go to [GitHub](https://github.com/backstage/backstage/tree/master/plugins) now, you’ll find everything you need to start collaborating with us to build out the docs-like-code Backstage plugin — we’ll call it TechDocs in the open as well.
-You’ll find the code in [techdocs](https://github.com/spotify/backstage/tree/master/plugins/techdocs) (frontend) and [techdocs-backend](https://github.com/spotify/backstage/tree/master/plugins/techdocs-backend). (There are also two separate packages [techdocs-cli](https://github.com/spotify/backstage/tree/master/packages/techdocs-cli) and [techdocs-container](https://github.com/spotify/backstage/tree/master/packages/techdocs-container).)
+You’ll find the code in [techdocs](https://github.com/backstage/backstage/tree/master/plugins/techdocs) (frontend) and [techdocs-backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend). (There are also two separate packages [techdocs-cli](https://github.com/backstage/techdocs-cli) and [techdocs-container](https://github.com/backstage/techdocs-container).)
-You’ll find issues to work on in the [issues queue](https://github.com/spotify/backstage/issues?q=is%3Aissue+is%3Aopen+label%3A%22docs-like-code%22+label%3A%22help+wanted%22), typically starting with TechDocs: and labeled with docs-like-code, some labeled good first issue. Feel free to add your own issues, of course.
+You’ll find issues to work on in the [issues queue](https://github.com/backstage/backstage/issues?q=is%3Aissue+is%3Aopen+label%3A%22docs-like-code%22+label%3A%22help+wanted%22), typically starting with TechDocs: and labeled with docs-like-code, some labeled good first issue. Feel free to add your own issues, of course.
diff --git a/microsite/blog/2020-09-23-backstage-cncf-sandbox.md b/microsite/blog/2020-09-23-backstage-cncf-sandbox.md
index bcfd7c6245..48a67e878c 100644
--- a/microsite/blog/2020-09-23-backstage-cncf-sandbox.md
+++ b/microsite/blog/2020-09-23-backstage-cncf-sandbox.md
@@ -1,6 +1,6 @@
---
title: Backstage has been accepted into the CNCF Sandbox
-author: Stefan Ålund
+author: Stefan Ålund, Spotify
authorURL: https://twitter.com/stalund
---
@@ -14,8 +14,8 @@ Backstage garnered quite a bit of interest from developers and organizations whe
Backstage’s ability to simplify tooling and standardize engineering practices has attracted interest from other major tech companies, as well as airlines, auto manufacturers, investment firms, and global retailers. We know that Backstage solves a problem — infrastructure complexity — that’s common to a lot of large and growing companies today. But different companies work differently, use particular toolsets, and have unique use cases. By making Backstage open source, we can build it with people working inside a variety of engineering organizations all over the world. It makes for a better product that serves a wider group of users (beyond that of Spotify’s) and their needs.
-The Backstage community is healthy and growing quickly. Over [130 people](https://github.com/spotify/backstage/graphs/contributors) have contributed to the project, and roughly 40% of pull requests are now coming from external, non-Spotify, contributors. With companies now deciding to [adopt Backstage](https://github.com/spotify/backstage/blob/master/ADOPTERS.md) we are also seeing a shift in the kinds of contributions we are getting from the community. It is truly amazing to see contributions to core parts of the platform as well as significant functionality additions through working [plugins](https://backstage.io/plugins).
+The Backstage community is healthy and growing quickly. Over [130 people](https://github.com/backstage/backstage/graphs/contributors) have contributed to the project, and roughly 40% of pull requests are now coming from external, non-Spotify, contributors. With companies now deciding to [adopt Backstage](https://github.com/backstage/backstage/blob/master/ADOPTERS.md) we are also seeing a shift in the kinds of contributions we are getting from the community. It is truly amazing to see contributions to core parts of the platform as well as significant functionality additions through working [plugins](https://backstage.io/plugins).
We’re excited to embark on this journey with the CNCF community. There’s so much great tech being built here, and it’s about time we share it to build even greater products, together. Entering into the CNCF Sandbox is just the first step. We are committed to working with the community to bring Backstage through the Incubation step, and finally all the way to becoming a Graduated, top-level project.
-Thanks to everyone for your support so far. We hope you [join us](https://mailchi.mp/spotify/backstage-community) in this next chapter of Backstage's journey. If you have questions or feedback, feel free to [email](mailto:alund@spotify.com) me directly.
+Thanks to everyone for your support so far. We hope you [join us](https://mailchi.mp/spotify/backstage-community) in this next chapter of Backstage's journey. If you have questions or feedback, feel free to [email](mailto:backstage-interest@spotify.com) me directly.
diff --git a/microsite/blog/2020-09-30-backstage-design-system.md b/microsite/blog/2020-09-30-backstage-design-system.md
index 4faea98782..fc227ea5d3 100644
--- a/microsite/blog/2020-09-30-backstage-design-system.md
+++ b/microsite/blog/2020-09-30-backstage-design-system.md
@@ -1,6 +1,6 @@
---
title: How to design for Backstage (even if you’re not a designer)
-author: Kat Zhou
+author: Kat Zhou, Spotify
authorURL: http://twitter.com/katherinemzhou
---
@@ -68,9 +68,9 @@ To keep up with our latest design guidelines, go to [Designing for Backstage](ht
-### [GitHub](https://github.com/spotify/backstage)
+### [GitHub](https://github.com/backstage/backstage)
-Join in on the action [at spotify/backstage on GitHub](https://github.com/spotify/backstage) by submitting issues and opening pull requests for all things related to components and patterns in Backstage.
+Join in on the action [at backstage/backstage on GitHub](https://github.com/backstage/backstage) by submitting issues and opening pull requests for all things related to components and patterns in Backstage.
diff --git a/microsite/blog/2020-09-30-plugin-marketplace.md b/microsite/blog/2020-09-30-plugin-marketplace.md
index 0b96abbc60..f4e9b749e2 100644
--- a/microsite/blog/2020-09-30-plugin-marketplace.md
+++ b/microsite/blog/2020-09-30-plugin-marketplace.md
@@ -1,6 +1,6 @@
---
title: The Plugin Marketplace is open
-author: Stefan Ålund
+author: Stefan Ålund, Spotify
authorURL: https://twitter.com/stalund
---
@@ -34,10 +34,10 @@ This grand vision is actually not that far off. Already today there is a growing
Not all plugins you need will be open source. Every company has their own homegrown tooling. Building internal plugins lets you tailor your version of Backstage to be a perfect fit for your infrastructure and software development needs. If you end up [building plugins](https://backstage.io/docs/plugins/create-a-plugin) that could be useful for other companies, please consider releasing them as open source and [add them to the Marketplace](https://backstage.io/docs/plugins/add-to-marketplace).
-If you start developing a plugin that you aim to release as open source, we suggest that you create a [new plugin Issue](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). This helps the community know what plugins are in development and opens up opportunities for collaboration. You can also use this process if you have an idea for a good plugin, but you need help building it.
+If you start developing a plugin that you aim to release as open source, we suggest that you create a [new plugin Issue](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). This helps the community know what plugins are in development and opens up opportunities for collaboration. You can also use this process if you have an idea for a good plugin, but you need help building it.
We are really excited to see all the amazing plugins that have already been built, and look forward to seeing even more ideas and collaboration as the Backstage community continues to grow.
-What plugins would you like to see in the Plugin Marketplace? [Tell us](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME)!
+What plugins would you like to see in the Plugin Marketplace? [Tell us](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME)!
_Special shout-out to community member [Iain Billett](https://github.com/iain-b) from [Roadie](https://roadie.io) for helping build and contribute the [Plugin Marketplace page](https://backstage.io/plugins) (as his first PR no less!)._
diff --git a/microsite/blog/2020-10-22-cost-insights-plugin.md b/microsite/blog/2020-10-22-cost-insights-plugin.md
index 421ebacdd2..c7ae9c492d 100644
--- a/microsite/blog/2020-10-22-cost-insights-plugin.md
+++ b/microsite/blog/2020-10-22-cost-insights-plugin.md
@@ -1,10 +1,10 @@
---
title: New Cost Insights plugin: The engineer’s solution to taming cloud costs
-author: Janisa Anandamohan
+author: Janisa Anandamohan, Spotify
authorURL: https://twitter.com/janisa_a
---
-How did Spotify save millions on cloud costs within a matter of months?? We made cost optimization just another part of the daily development process. Our newly open sourced [Cost Insights plugin](https://github.com/spotify/backstage/tree/master/plugins/cost-insights) makes a team’s cloud costs visible — and actionable — right inside Backstage. So engineers can see the impact of their cloud usage (down to a product and resource level) and make optimizations wherever and whenever it makes sense. By managing cloud costs from the ground up, you can make smarter decisions that let you continue to build and scale quickly, without wasting resources.
+How did Spotify save millions on cloud costs within a matter of months?? We made cost optimization just another part of the daily development process. Our newly open sourced [Cost Insights plugin](https://github.com/backstage/backstage/tree/master/plugins/cost-insights) makes a team’s cloud costs visible — and actionable — right inside Backstage. So engineers can see the impact of their cloud usage (down to a product and resource level) and make optimizations wherever and whenever it makes sense. By managing cloud costs from the ground up, you can make smarter decisions that let you continue to build and scale quickly, without wasting resources.
@@ -59,7 +59,7 @@ Engineers can then determine for themselves if the time invested in an optimizat
## Getting started
-You can begin working with the Cost Insights plugin today on [GitHub](https://github.com/spotify/backstage/tree/master/plugins/cost-insights). We include an example client with static data in the expected format. The `CostInsightsApi` should talk with a cloud billing backend that aggregates billing data from your cloud provider.
+You can begin working with the Cost Insights plugin today on [GitHub](https://github.com/backstage/backstage/tree/master/plugins/cost-insights). We include an example client with static data in the expected format. The `CostInsightsApi` should talk with a cloud billing backend that aggregates billing data from your cloud provider.
The current release of Cost Insights includes:
@@ -72,8 +72,8 @@ The current release of Cost Insights includes:
Our hope is to help other companies translate their cloud cost in a relatable way for their engineers to better understand their impact and accurately identify their opportunities for optimizations.
-And if you’re interested in contributing to our outstanding issues, you can find them in the issues queue, filtered under the [‘cost-insights’ label](https://github.com/spotify/backstage/labels/cost-insights).
+And if you’re interested in contributing to our outstanding issues, you can find them in the issues queue, filtered under the [‘cost-insights’ label](https://github.com/backstage/backstage/labels/cost-insights).
## Ready for DevSecCostOpsPlus (and whatever’s next)
-There’s DevOps, there’s DevSecOps, and then there’s Backstage: one frontend for all your infrastructure. From building, testing, and deploying to monitoring and security — Backstage helps you manage your entire tech organization and provides a seamless developer experience for engineers, from end to end to end. And now that also extends to cost management for your cloud infrastructure and tooling. Happy building and [happy optimizing](https://github.com/spotify/backstage/tree/master/plugins/cost-insights).
+There’s DevOps, there’s DevSecOps, and then there’s Backstage: one frontend for all your infrastructure. From building, testing, and deploying to monitoring and security — Backstage helps you manage your entire tech organization and provides a seamless developer experience for engineers, from end to end to end. And now that also extends to cost management for your cloud infrastructure and tooling. Happy building and [happy optimizing](https://github.com/backstage/backstage/tree/master/plugins/cost-insights).
diff --git a/microsite/blog/2020-12-22-stability-index.md b/microsite/blog/2020-12-22-stability-index.md
new file mode 100644
index 0000000000..95074a13a2
--- /dev/null
+++ b/microsite/blog/2020-12-22-stability-index.md
@@ -0,0 +1,42 @@
+---
+title: Announcing the Backstage Stability Index
+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.
+
+
+
+
+
+Backstage has a great and growing community of users and contributors. With so much valuable feedback, this inevitably means that sometimes we will go back and revise design decisions that introduce breaking changes. Furthermore, as we continue to ship new features and systems, we’ll continue this cycle of iterating, gathering feedback, and iterating again before reaching a stable API.
+
+This rapid evolution can create uncertainty around which parts of the project are considered stable and which are not. Regardless of whether you're contributing to the project directly, setting up your own Backstage, or building plugins, you will be using various parts of the project that vary in stability. While many API surfaces of Backstage are reasonably solid and are unlikely to see any big breaking changes, others are more unstable or experimental.
+
+## The Stability Index
+
+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:
+
+- **0** — There's a changelog entry.
+- **1** — There's a migration guide.
+- **2** — Two weeks of deprecation.
+- **3** — Three months of deprecation.
+
+The Stability Index has been tailored for the phase that the project is currently in, and we do not intend to keep it in place in its current form forever. It is, for example, likely that we in the future will increase the deprecation time limits.
+
+## Staying up to date
+
+In addition to the Stability Index, we have also recently adopted a weekly release cadence where we cut new releases every Thursday. Along with the two-week deprecation period of many of the API surfaces in Backstage, there is an excellent opportunity to form a routine to update your own Backstage projects either weekly or biweekly.
+
+In order to make the update process easier, we’ve added a new command to the Backstage CLI that allows you to easily update your project to use the latest Backstage release. The command is called `version:bump` and is executed in the root of your project using the CLI. You can see what it looks like in action below.
+
+
+
+## Impact
+
+The Stability Index has already been active for a couple of weeks, and we have immediately seen an impact on the consideration and care taken when working in parts of the project that we have committed to keeping more stable. Both members of the core maintainer team and contributors from the community have taken care to roll out updates responsibly, with examples such as [PR #3524](https://github.com/backstage/backstage/pull/3524) and [PR #3465](https://github.com/backstage/backstage/pull/3465).
+
+The core team is working hard to bring more stability to broader parts of Backstage, and engineering it in a way that allows for long-term evolution. There are more learnings to be discovered as we continue evolving Backstage, but we are confident that the Stability Index will allow for a clearer path and a smoother ride for everyone involved!
diff --git a/microsite/blog/assets/2020-12-22/stability-index-hero.gif b/microsite/blog/assets/2020-12-22/stability-index-hero.gif
new file mode 100644
index 0000000000..6459d241e2
Binary files /dev/null and b/microsite/blog/assets/2020-12-22/stability-index-hero.gif differ
diff --git a/microsite/blog/assets/2020-12-22/versions-bump.png b/microsite/blog/assets/2020-12-22/versions-bump.png
new file mode 100644
index 0000000000..2a8d624687
Binary files /dev/null and b/microsite/blog/assets/2020-12-22/versions-bump.png differ
diff --git a/microsite/core/Footer.js b/microsite/core/Footer.js
index 1bebf2f399..1471d7b4d1 100644
--- a/microsite/core/Footer.js
+++ b/microsite/core/Footer.js
@@ -17,19 +17,6 @@
const React = require('react');
class Footer extends React.Component {
- docUrl(doc, language) {
- const baseUrl = this.props.config.baseUrl;
- const docsUrl = this.props.config.docsUrl;
- const docsPart = `${docsUrl ? `${docsUrl}/` : ''}`;
- const langPart = `${language ? `${language}/` : ''}`;
- return `${baseUrl}${docsPart}${langPart}${doc}`;
- }
-
- pageUrl(doc, language) {
- const baseUrl = this.props.config.baseUrl;
- return baseUrl + (language ? `${language}/` : '') + doc;
- }
-
render() {
return (