Merge branch 'master' of github.com:backstage/backstage into mob/scaffolder-cra-fixes

* 'master' of github.com:backstage/backstage: (758 commits)
  add zalando to adpoters list
  Avoid passing undefined to values that are marked as optional
  Support profile of groups in LdapOrgReaderProcessor
  Import picture and display name by the GitHubOrgReaderProcessor
  Use the new group profile section in the group profile card
  Add support for the group profile element to Microsoft Graph processor
  Add profile section to group entity
  Implement readTree on BitBucketUrlReader - Add getBitbucketDefaultBranch
  Implement readTree on BitBucketUrlReader - Modify changeset
  Implement readTree on BitBucketUrlReader - Implement getBitbucketDownloadUrl and remove hash for Bitbucket Server
  Implement readTree on BitBucketUrlReader
  WIP: implement readTree for bitbucket
  updated scaffolder config.d to avoid config failure
  build(deps): bump swagger-ui-react from 3.37.2 to 3.38.0
  included changeset
  Introduced config schema for plugins/scaffolder-backend
  Write relations directly as part of batch add / update of entities.
  Add codeowners for techdocs-common package
  techdocs-common: Add type dependencies
  Update nice-trains-punch.md
  ...

.changeset/2863.md

@@ -1,29 +0,0 @@
----
-'@backstage/core-api': patch
----
-
-Updated the AuthApi `.create` methods to configure the default scope of the corresponding Auth Api. As a result the
-default scope is configurable when overwriting the Core Api in the app.
-
-```
-GithubAuth.create({
-  discoveryApi,
-  oauthRequestApi,
-  defaultScopes: ['read:user', 'repo'],
-}),
-```
-
-Replaced redundant CreateOptions of each Auth Api with the OAuthApiCreateOptions type.
-
-```
-export type OAuthApiCreateOptions = AuthApiCreateOptions & {
-  oauthRequestApi: OAuthRequestApi;
-  defaultScopes?: string[];
-};
-
-export type AuthApiCreateOptions = {
-  discoveryApi: DiscoveryApi;
-  environment?: string;
-  provider?: AuthProvider & { id: string };
-};
-```

.changeset/3157.md

@@ -1,16 +0,0 @@
----
-'@backstage/core': patch
----
-
-Adds the MarkdownContent component to render and display Markdown content with the default
-[GFM](https://github.github.com/gfm/) (Github flavored Markdown) dialect.
-
-```
-<MarkdownContent content={markdownGithubFlavored} />
-```
-
-To render the Markdown content with plain [CommonMark](https://commonmark.org/), set the dialect to `common-mark`
-
-```
-<MarkdownContent content={markdown} dialect='common-mark />
-```

.changeset/3194.md

@@ -1,7 +0,0 @@
----
-'@backstage/core': patch
----
-
-Extend default config loader to read config from the window object.
-
-Config will be read from `window.__APP_CONFIG__` which should be an object.

.changeset/calm-emus-push.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-jenkins': minor
----
-
-Add tooltip for Jenkins rerun button

.changeset/calm-scissors-jam.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Add support for Github Enterprise in GitHubOrgReaderProcessor so you can properly ingest users of a GHE organization.

.changeset/cost-insights-quick-suits-brake.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-cost-insights': patch
----
-
-Fix styling issue on Cost Insights product panels with no cost

.changeset/cost-insights-tasty-years-laugh.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-cost-insights': patch
+---
+
+pin all projects selection to the top of menu list

.changeset/curvy-dodos-fry.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Break the refresh loop into several smaller transactions

.changeset/dirty-melons-retire.md

@@ -0,0 +1,6 @@
+---
+'@backstage/catalog-model': patch
+---
+
+Introduce a `profile` section for group entities that can optional include a
+`displayName`, `email` and `picture`.

.changeset/dirty-wolves-wink.md

@@ -0,0 +1,7 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Support `profile` of groups including `displayName`, `email`, and `picture` in
+`LdapOrgReaderProcessor`. The source fields for them can be configured in the
+`ldapOrg` provider.

.changeset/dry-pillows-carry.md

@@ -1,6 +0,0 @@
----
-'@backstage/core': patch
----
-
-- The BottomLink is now able to handle with internal routes.
-- @backstage/core Link component detect whether it's an external link or not, and render accordingly

.changeset/early-dots-drive.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-org': patch
+---
+
+Ensure a name is always displayed for user entities in the org plugin. This can happen when there is no profile
+displayName provided (e.g. a GitHub user that has not added a name to their profile)

.changeset/fluffy-dragons-cry.md

@@ -1,5 +0,0 @@
----
-'@backstage/core': patch
----
-
-Extend the table to share its current filter state. The filter state can be used together with the new `useQueryParamState` hook to store the current filter state to the browser history and restore it after navigating to other routes.

.changeset/friendly-carpets-repeat.md

@@ -0,0 +1,45 @@
+---
+'@backstage/techdocs-common': minor
+'@backstage/plugin-techdocs': minor
+'@backstage/plugin-techdocs-backend': minor
+---
+
+_Breaking changes_
+
+1. Added option to use Google Cloud Storage as a choice to store the static generated files for TechDocs.
+   It can be configured using `techdocs.publisher.type` option in `app-config.yaml`.
+   Step-by-step guide to configure GCS is available here https://backstage.io/docs/features/techdocs/using-cloud-storage
+   Set `techdocs.publisher.type` to `'local'` if you want to continue using local filesystem to store TechDocs files.
+
+2. `techdocs.builder` is now required and can be set to `'local'` or `'external'`. (Set it to `'local'` for now, since CI/CD build
+   workflow for TechDocs will be available soon (in few weeks)).
+   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.
+   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 in the CI/CD pipeline of the repository.
+   TechDocs will not assume a default value for `techdocs.builder`. It is better to explicitly define it in the `app-config.yaml`.
+
+3. When configuring TechDocs in your backend, there is a difference in how a new publisher is created.
+
+```
+---  const publisher = new LocalPublish(logger, discovery);
++++  const publisher = Publisher.fromConfig(config, logger, discovery);
+```
+
+Based on the config `techdocs.publisher.type`, the publisher could be either Local publisher or Google Cloud Storage publisher.
+
+4. `techdocs.storageUrl` is now a required config. Should be `http://localhost:7000/api/techdocs/static/docs` in most setups.
+
+5. Parts of `@backstage/plugin-techdocs-backend` have been moved to a new package `@backstage/techdocs-common` to generate docs. Also to publish docs
+   to-and-fro between TechDocs and a storage (either local or external). However, a Backstage app does NOT need to import the `techdocs-common` package -
+   app should only import `@backstage/plugin-techdocs` and `@backstage/plugin-techdocs-backend`.
+
+_Patch changes_
+
+1. See all of TechDocs config options and its documentation https://backstage.io/docs/features/techdocs/configuration
+
+2. Logic about serving static files and metadata retrieval have been abstracted away from the router in `techdocs-backend` to the instance of publisher.
+
+3. Removed Material UI Spinner from TechDocs header. Spinners cause unnecessary UX distraction.
+   Case 1 (when docs are built and are to be served): Spinners appear for a split second before the name of site shows up. This unnecessarily distracts eyes because spinners increase the size of the Header. A dot (.) would do fine. Definitely more can be done.
+   Case 2 (when docs are being generated): There is already a linear progress bar (which is recommended in Storybook).

.changeset/friendly-olives-breathe.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-auth-backend': patch
+---
+
+Added configuration schema for the commonly used properties

.changeset/gorgeous-scissors-jog.md

@@ -0,0 +1,6 @@
+---
+'@backstage/core': patch
+'@backstage/plugin-org': patch
+---
+
+Add a `<Avatar>` component to `@backstage/core`.

.changeset/grumpy-elephants-press.md

@@ -0,0 +1,6 @@
+---
+'@backstage/backend-common': patch
+'@backstage/integration': patch
+---
+
+Implement readTree on BitBucketUrlReader and getBitbucketDownloadUrl

.changeset/heavy-ducks-raise.md

@@ -0,0 +1,5 @@
+---
+'@backstage/catalog-model': patch
+---
+
+Ignore relations when comparing entities. This stops the refresh loop from rewriting entities over and over.

.changeset/lucky-lemons-return.md

@@ -1,5 +0,0 @@
----
-'@backstage/create-app': patch
----
-
-Fix missing api-docs plugin registration in app template

.changeset/moody-pugs-smoke.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-user-settings': patch
----
-
-Export `AuthProviders`, `DefaultProviderSettings` and `ProviderSettingsItem`.

.changeset/nice-trains-punch.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-pagerduty': patch
+---
+
+Supporting Timezones

.changeset/odd-mugs-build.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Support `profile` of groups including `displayName` and `picture` in
+`GithubOrgReaderProcessor`. Fixes the import of `description` for groups.

.changeset/odd-parents-push.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-api-docs': patch
----
-
-Persist table state of the API Explorer to the browser history. This allows to navigate between pages and come back to the previous filter state.

.changeset/purple-cycles-switch.md

@@ -0,0 +1,26 @@
+---
+'@backstage/plugin-catalog-backend': minor
+---
+
+Write relations directly as part of batch add / update of entities.
+
+Slight change of the `CommonDatabase` contract:
+
+## `addEntity` removed
+
+This method was unused by the core, and rendered unnecessary when `addEntities`
+exists.
+
+If you were a user of `addEntity`, please call `addEntities` instead, with an
+array of one element.
+
+## `DbEntityRequest` has a new field `relations`
+
+This is the structure that is passed to `addEntities` and `updateEntity`. It
+used to be the case that you needed to call `setRelations` separately, but now
+this instead happens directly when you call `addEntities` or `updateEntity`.
+
+If you were using `addEntities` or `updateEntity` directly, please adapt your
+code to add the `relations` array to each request. If you were calling
+`setRelations` separately next to these methods, you no longer need to do so,
+after adding the relations to the `DbEntityRequest`s.

.changeset/rare-peas-accept.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Batch the writing of statuses after refreshes. This reduced the runtime on sqlite from 16s to 0.2s, and on pg from 60s to 1s on my machine, for the huge LDAP set.

.changeset/rotten-pandas-draw.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Add index to foreign key columns. Postgres (and others) do not do this on the "source" side of a foreign key relation, which was what led to the slowness on large datasets. The full LDAP dataset ingestion now takes two minutes, which is not optimal yet but still a huge improvement over before when it basically never finished :)

.changeset/seven-monkeys-run.md

@@ -1,5 +0,0 @@
----
-'@backstage/core': patch
----
-
-Make the selected state of Select and CheckboxTree controllable from outside.

.changeset/shaggy-bobcats-warn.md

@@ -1,5 +0,0 @@
----
-'@backstage/core': minor
----
-
-New DependencyGraph component added to core package.

.changeset/shiny-grapes-tan.md

@@ -0,0 +1,5 @@
+---
+'@backstage/integration': patch
+---
+
+Validate that integration config contains a valid host

.changeset/silent-dodos-repeat.md

@@ -1,5 +0,0 @@
----
-'@backstage/core': patch
----
-
-Fix divider prop not respected on InfoCard

.changeset/six-mugs-camp.md

@@ -0,0 +1,20 @@
+---
+'@backstage/create-app': patch
+---
+
+In the techdocs-backend plugin (`packages/backend/src/plugins/techdocs.ts`), create a publisher using
+
+```
+  const publisher = Publisher.fromConfig(config, logger, discovery);
+```
+
+instead of
+
+```
+  const publisher = new LocalPublish(logger, discovery);
+```
+
+An instance of `publisher` can either be a local filesystem publisher or a Google Cloud Storage publisher.
+
+Read more about the configs here https://backstage.io/docs/features/techdocs/configuration
+(You will also have to update `techdocs.storage.type` to `local` or `googleGcs`. And `techdocs.builder` to either `local` or `external`.)

.changeset/smooth-hairs-breathe.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-tech-radar': patch
----
-
-Make the footer color of the tech-radar work in both light and dark theme.

.changeset/spicy-bananas-help.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-api-docs': patch
----
-
-Upgrade @kyma-project/asyncapi-react to 0.14.2

.changeset/strong-moose-cough.md

@@ -1,5 +0,0 @@
----
-'@backstage/theme': patch
----
-
-Improve styling of outlined chips in dark mode.

.changeset/swift-sheep-ring.md

@@ -0,0 +1,5 @@
+---
+'@backstage/cli': patch
+---
+
+Re-enable symlink resolution during bundling, and switch to using a resolve plugin for external linked packages.

.changeset/tender-coats-unite.md

@@ -0,0 +1,11 @@
+---
+'@backstage/plugin-org': patch
+---
+
+Display the new `profile` fields (`displayName`, `email`, and `picture`) for
+groups on the `GroupProfileCard`.
+
+![Groups Profile Section](./groups_profile.png)
+
+This also resolves some cases where `profile` fields are missing for users or
+groups and for example falls back to displaying the entity name. Adds additional test data to the ACME Corp dataset.

.changeset/thick-lobsters-swim.md

@@ -1,5 +0,0 @@
----
-'@backstage/plugin-catalog': patch
----
-
-Improved the edit link to open the component yaml in edit mode in corresponding SCM. Broke out logic for createEditLink to be reused.

.changeset/weak-otters-love.md

@@ -1,16 +0,0 @@
----
-'@backstage/plugin-scaffolder': minor
-'@backstage/plugin-scaffolder-backend': minor
----
-
-`createRouter` of scaffolder backend will now require additional option as `entityClient` which could be generated by `CatalogEntityClient` in `plugin-scaffolder-backend` package. Here is example to generate `entityClient`.
-
-```js
-import { CatalogEntityClient } from '@backstage/plugin-scaffolder-backend';
-import { SingleHostDiscovery } from '@backstage/backend-common';
-
-const discovery = SingleHostDiscovery.fromConfig(config);
-const entityClient = new CatalogEntityClient({ discovery });
-```
-
-- Scaffolder's API `/v1/jobs` will accept `templateName` instead of `template` Entity.

.changeset/weak-rice-beam.md

@@ -1,5 +0,0 @@
----
-'@backstage/backend-common': patch
----
-
-Capture plugin name under the /api/ prefix for http metrics

.changeset/weak-sloths-prove.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Added configuration schema for the commonly used properties

.changeset/wet-garlics-shave.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-sentry': patch
+---
+
+Added configuration schema for the commonly used properties

.changeset/witty-scissors-divide.md

@@ -0,0 +1,7 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Support `profile` of groups including `displayName` and `email` in
+`MicrosoftGraphOrgReaderProcessor`. Importing `picture` doesn't work yet, as
+the Microsoft Graph API does not expose them correctly.

.github/CODEOWNERS

@@ -8,6 +8,8 @@
 /docs/features/techdocs                     @backstage/techdocs-core
 /plugins/cost-insights                      @backstage/silver-lining
 /plugins/cloudbuild                         @trivago/ebarrios
+/plugins/search                             @backstage/techdocs-core
 /plugins/techdocs                           @backstage/techdocs-core
 /plugins/techdocs-backend                   @backstage/techdocs-core
+/packages/techdocs-common                   @backstage/techdocs-core
 /.changeset/cost-insights-*                 @backstage/silver-lining

.github/styles/vocab.txt

@@ -1,4 +1,5 @@
 abc
+andrewthauer
 Apdex
 api
 Api
@@ -9,21 +10,25 @@ async
 Avro
 backrub
 Balachandran
+benjdlambert
 Bigtable
+Billett
 Blackbox
 bool
 boolean
+builtins
 Chai
 changeset
 changesets
 Changesets
-changset
 chanwit
 Chanwit
+ci
 cisphobia
 cissexist
 classname
 cli
+cloudbuild
 cncf
 codeblocks
 Codecov
@@ -38,6 +43,7 @@ const
 cookiecutter
 css
 dariddler
+dataflow
 deadnaming
 destructured
 dev
@@ -50,6 +56,7 @@ Dockerfile
 Dockerize
 dockerode
 Docusaurus
+dzolotusky
 eg
 Ek
 env
@@ -59,13 +66,17 @@ facto
 failover
 Figma
 Firekube
+Fiverr
+freben
 Fredrik
 github
-Github
+GitHub
 gitlab
-Gitlab
+GitLab
+Grafana
 graphql
 graphviz
+Gustavsson
 Hackathons
 haproxy
 heroku
@@ -74,8 +85,10 @@ horizontalpodautoscalers
 Hostname
 http
 https
+Iain
 img
 incentivised
+inlined
 inlinehilite
 interop
 javascript
@@ -92,8 +105,8 @@ learnings
 lerna
 Lerna
 magiclink
-Maintainership
 mailto
+maintainership
 Malus
 md
 microsite
@@ -110,6 +123,7 @@ msw
 namespace
 namespaces
 Namespaces
+namespacing
 neuro
 newrelic
 nginx
@@ -120,6 +134,7 @@ npm
 nvm
 oauth
 Oauth
+oidc
 Okta
 Oldsberg
 onboarding
@@ -158,28 +173,36 @@ Rollup
 Rosaceae
 rst
 rsync
+rugvip
 ruleset
 sam
 scaffolded
 scaffolder
 Scaffolder
 semlas
+semver
 Serverless
 Sinon
 smartsymobls
+Snyk
 sparklines
 Spotifiers
 spotify
 Spotify
+sqlite
 squidfunk
 src
+stefanalund
 subkey
+subtree
 superfences
 Superfences
+superset
 talkdesk
 Talkdesk
 tasklist
 techdocs
+Telenor
 templated
 templater
 Templater
@@ -190,10 +213,13 @@ theres
 toc
 tolerations
 Tolerations
+toolchain
 toolsets
 tooltip
+tooltips
 touchpoints
 ui
+untracked
 upvote
 url
 utils
@@ -202,14 +228,11 @@ Voi
 Wealthsimple
 Weaveworks
 Webpack
+www
+WWW
 xyz
 yaml
 Zalando
 Zhou
-Billett
-cloudbuild
-Grafana
-Iain
-Snyk
-www
-WWW
+Zolotusky
+zoomable

.github/workflows/changeset.yml

@@ -19,4 +19,4 @@ jobs:
           # Calls out to `changeset version`, but also runs prettier
           version: yarn release
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}

.github/workflows/ci.yml

@@ -72,6 +72,9 @@ jobs:
       - name: prettier
         run: yarn prettier:check
 
+      - name: validate config
+        run: yarn backstage-cli config:check
+
       - name: lint
         run: yarn lerna -- run lint --since origin/master
 

.github/workflows/e2e-win.yml

@@ -32,7 +32,7 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
       - name: Add msbuild to PATH
-        uses: microsoft/setup-msbuild@v1.0.1
+        uses: microsoft/setup-msbuild@v1.0.2
       - name: yarn install
         run: yarn install --frozen-lockfile
 

.github/workflows/master.yml

@@ -47,6 +47,9 @@ jobs:
         run: yarn install --frozen-lockfile
       # End of yarn setup
 
+      - name: validate config
+        run: yarn backstage-cli config:check
+
       - name: lint
         run: yarn lerna -- run lint
 

.github/workflows/nightly.yml

@@ -62,7 +62,7 @@ jobs:
       - name: prepare nightly release
         run: yarn changeset version --snapshot nightly
 
-      # Publishes the nightly release to NPM, by using tag we make sure the release is
+      # Publishes the nightly release to npm, by using tag we make sure the release is
       # not flagged as the latest release, which means that people will not get this
       # version of the package unless requested explicitly
       - name: publish nightly release

.github/workflows/techdocs-project-board.yml

@@ -1,6 +1,7 @@
 name: Automatically add new TechDocs Issues and PRs to the GitHub project board
-# Development of TechDocs in Backstage is managed by this Kanban board - https://github.com/backstage/backstage/projects/5
-# New issues with TechDocs in their title or docs-like-code label will be added to the board.
+# Development of TechDocs in Backstage is managed by this Kanban board - https://github.com/orgs/backstage/projects/1
+# New issues and PRs with TechDocs in their title or docs-like-code label will be added to the board.
+# Caveat: New PRs created from forks will not be added since GitHub Actions don't share credentials with forks.
 
 on:
   issues:
@@ -9,7 +10,7 @@ on:
     types: [opened, reopened, labeled, edited]
 
 env:
-  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  MY_GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}
 
 jobs:
   assign_issue_or_pr_to_project:
@@ -23,7 +24,7 @@ jobs:
           contains(github.event.issue.title, 'techdocs') ||
           contains(github.event.issue.title, 'Techdocs')
         with:
-          project: 'https://github.com/backstage/backstage/projects/5'
+          project: 'https://github.com/orgs/backstage/projects/1'
           column_name: 'Incoming'
 
       - name: Assign new issue to Incoming based on its label.
@@ -31,7 +32,7 @@ jobs:
         if: |
           contains(github.event.issue.labels.*.name, 'docs-like-code')
         with:
-          project: 'https://github.com/backstage/backstage/projects/5'
+          project: 'https://github.com/orgs/backstage/projects/1'
           column_name: 'Incoming'
 
       - name: Assign new PR to Incoming based on its title.
@@ -41,7 +42,7 @@ jobs:
           contains(github.event.pull_request.title, 'techdocs') ||
           contains(github.event.pull_request.title, 'Techdocs')
         with:
-          project: 'https://github.com/backstage/backstage/projects/5'
+          project: 'https://github.com/orgs/backstage/projects/1'
           column_name: 'Incoming'
 
       - name: Assign new PR to Incoming based on its label.
@@ -49,5 +50,5 @@ jobs:
         if: |
           contains(github.event.pull_request.labels.*.name, 'docs-like-code')
         with:
-          project: 'https://github.com/backstage/backstage/projects/5'
+          project: 'https://github.com/orgs/backstage/projects/1'
           column_name: 'Incoming'

.gitignore

@@ -96,6 +96,7 @@ typings/
 .nuxt
 dist
 dist-types
+dist-workspace
 
 # Gatsby files
 .cache/

.yarnrc

@@ -6,4 +6,4 @@ registry "https://registry.npmjs.org/"
 disable-self-update-check true
 lastUpdateCheck 1580389148099
 yarn-path ".yarn/releases/yarn-1.22.1.js"
-network-timeout 600000
+network-timeout 300000

ADOPTERS.md

@@ -1,15 +1,18 @@
-| Organization                                 | Contact                                                      | Description of Use                                                                               |
-| -------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
-| [Spotify](https://www.spotify.com)           | [@stefanalund](https://github.com/stefanalund)               | Main interface towards all of Spotify's infrastructure and technical documentation.              |
-| [bol.com](https://www.bol.com)               | [@RoyJacobs](https://github.com/RoyJacobs)                   | Initial work being done to unify platform tooling.                                               |
-| [DFDS](https://www.dfds.com)                 | [@carlsendk](https://github.com/carlsendk)                   | V2 self-service platform.                                                                        |
-| [Roadie](https://roadie.io)                  | [@dtuite](https://github.com/dtuite)                         | Hosted, managed Backstage with easy set-up                                                       |
-| [Roku](https://www.roku.com)                 | [@timurista](https://github.com/timurista)                   | Initial work on Cloud engineering service platform.                                              |
-| [SDA SE](https://sda.se)                     | [@Fox32](https://github.com/Fox32)                           | Central place for developing and sharing services in our insurance ecosystem.                    |
-| [H-E-B](https://www.heb.com)                 | [@german-j-rodriguez](https://github.com/german-j-rodriguez) | Initial work on Engineering Portal service platform.                                             |
-| [American Airlines](https://www.aa.com)      | [@paulpach](https://github.com/paulpach)                     | Central place for developers to develop and maintain applications                                |
-| [Kiwi.com](https://kiwi.com)                 | [@aexvir](https://github.com/aexvir)                         | Replacing the frontend of [The Zoo](https://github.com/kiwicom/the-zoo), their service registry. |
-| [Voi](https://www.voiscooters.com/)          | [@K-Phoen](https://github.com/K-Phoen)                       | Developer portal, main gateway to our infrastructure, documentation and internal tooling.        |
-| [Talkdesk](https://www.talkdesk.com)         | [@jaime-talkdesk](https://github.com/jaime-talkdesk)         | Initial work for Engineering Portal and Self Provisioning to R&D                                 |
-| [Wealthsimple](https://www.wealthsimple.com) | [@andrewthauer](https://github.com/andrewthauer)             | Developer portal, service catalog, documentation and tooling                                     |
-| [Grab](https://www.grab.com)                 | [@althafh](https://github.com/althafh)                       | Initial work as a unified interface for all of Grab's internal tooling                           |
+| Organization                                 | Contact                                                      | Description of Use                                                                                                                     |
+| -------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [Spotify](https://www.spotify.com)           | [@stefanalund](https://github.com/stefanalund)               | Main interface towards all of Spotify's infrastructure and technical documentation.                                                    |
+| [bol.com](https://www.bol.com)               | [@RoyJacobs](https://github.com/RoyJacobs)                   | Initial work being done to unify platform tooling.                                                                                     |
+| [DFDS](https://www.dfds.com)                 | [@carlsendk](https://github.com/carlsendk)                   | V2 self-service platform.                                                                                                              |
+| [Roadie](https://roadie.io)                  | [@dtuite](https://github.com/dtuite)                         | Hosted, managed Backstage with easy set-up                                                                                             |
+| [Roku](https://www.roku.com)                 | [@timurista](https://github.com/timurista)                   | Initial work on Cloud engineering service platform.                                                                                    |
+| [SDA SE](https://sda.se)                     | [@Fox32](https://github.com/Fox32)                           | Central place for developing and sharing services in our insurance ecosystem.                                                          |
+| [H-E-B](https://www.heb.com)                 | [@german-j-rodriguez](https://github.com/german-j-rodriguez) | Initial work on Engineering Portal service platform.                                                                                   |
+| [American Airlines](https://www.aa.com)      | [@paulpach](https://github.com/paulpach)                     | Central place for developers to develop and maintain applications                                                                      |
+| [Kiwi.com](https://kiwi.com)                 | [@aexvir](https://github.com/aexvir)                         | Replacing the frontend of [The Zoo](https://github.com/kiwicom/the-zoo), their service registry.                                       |
+| [Voi](https://www.voiscooters.com/)          | [@K-Phoen](https://github.com/K-Phoen)                       | Developer portal, main gateway to our infrastructure, documentation and internal tooling.                                              |
+| [Talkdesk](https://www.talkdesk.com)         | [@jaime-talkdesk](https://github.com/jaime-talkdesk)         | Initial work for Engineering Portal and Self Provisioning to R&D                                                                       |
+| [Wealthsimple](https://www.wealthsimple.com) | [@andrewthauer](https://github.com/andrewthauer)             | Developer portal, service catalog, documentation and tooling                                                                           |
+| [Grab](https://www.grab.com)                 | [@althafh](https://github.com/althafh)                       | Initial work as a unified interface for all of Grab's internal tooling                                                                 |
+| [Telenor Sweden](https://www.telenor.se)     | [@O5ten](https://github.com/O5ten)                           | Building a developer portal for scaffolding projects towards our unified build environment and microservice stacks                     |
+| [Fiverr](https://www.fiverr.com)             | [@nirga](https://github.com/nirga)                           | Unifying separate tools that developers are using today (i.e. monitoring, dead letter queues management, etc.) into a single platform. |
+| [Zalando SE](https://www.zalando.de)         | [@leviferreira](https://github.com/leviferreira)             | Building V2 of the Internal Development Portal.                                                                                        |

CHANGELOG.md

@@ -1,13 +1,9 @@
 # Backstage Changelog
 
-This is a best-effort changelog where we manually collect breaking changes. It is not an exhaustive list of all changes or even features added.
+This changelog is no longer being updated and will be removed in the future, as each package now has its own changelog instead. It was a best-effort changelog where we manually collected breaking changes during the `v0.1.1-alpha.<n>` releases.
 
 If you encounter issues while upgrading to a newer version, don't hesitate to reach out on [Discord](https://discord.gg/EBHEGzX) or [open an issue](https://github.com/backstage/backstage/issues/new/choose)!
 
-## Next Release
-
-> Collect changes for the next release below
-
 ## v0.1.1-alpha.26
 
 ### @backstage/cli

GOVERNANCE.md

@@ -1,52 +1,45 @@
-# Backstage Governance
+# Process for becoming a maintainer
 
-This document defines project governance for the project.
+## a) Your organization is not yet a maintainer
 
-## Maintainers
+- Express interest to the sponsors that your organization is interested in becoming a maintainer. Becoming a maintainer generally means that you are going to be spending substantial time on Backstage for the foreseeable future. You should have domain expertise and be extremely proficient in TypeScript.
+- We will expect you to start contributing increasingly complicated PRs, under the guidance of the existing maintainers.
+- We may ask you to do some PRs from our backlog.
+- As you gain experience with the code base and our standards, we will ask you to do code reviews for incoming PRs.
+- After a period of approximately 2-3 months of working together and making sure we see eye to eye, the existing sponsors and maintainers will confer and decide whether to grant maintainer status or not. We make no guarantees on the length of time this will take, but 2-3 months is the approximate goal.
 
-Backstage Maintainers have write access to the Backstage GitHub repository https://github.com/backstage/backstage. The current maintainers can be found in [MAINTAINERS](MAINTAINERS.md).
-
-This privilege is granted with some expectation of responsibility: maintainers are people who care about the Backstage project and want to help it grow and improve. A maintainer is not just someone who can make changes, but someone who has demonstrated his or her ability to collaborate with the team, get the most knowledgeable people to review code, contribute high-quality code, and follow through to fix issues (in code or tests).
-
-A maintainer is a contributor to the Backstage project's success and a citizen helping the project succeed.
-
-## Becoming a Maintainer
+## b) Your organization is currently a maintainer
 
 To become a maintainer you need to demonstrate the following:
 
-- commitment to the project
-  - participate in discussions, contributions, code reviews for 3 months or more,
-  - perform code reviews for 10 non-trivial pull requests,
-  - contribute 10 non-trivial pull requests and have them merged into master,
-- ability to write good code,
-- ability to collaborate with the team,
-- understanding of how the team works (policies, processes for testing and code review, etc),
-- understanding of the project's code base and coding style.
+- First decide whether your organization really needs more people with maintainer access. Valid reasons are "blast radius", a large organization that is working on multiple unrelated projects, etc.
+- Contact a sponsor for your organization and express interest.
+- Start doing PRs and code reviews under the guidance of your maintainer.
+- After a period of 1-2 months the existing sponsors will discuss granting maintainer access.
+- Maintainer access can be upgraded to sponsor access after another conference of the existing sponsors.
 
-## Changes in Maintainership
+# Maintainer responsibilities
 
-A new maintainer must be proposed by an existing maintainer by opening an issue (with title `Maintainer Nomination`) to the Backstage GitHub repository (https://github.com/backstage/backstage) containing the following information:
+- Monitor email aliases.
+- Monitor Discord (delayed response is perfectly acceptable).
+- Triage GitHub issues and perform pull request reviews for other maintainers and the community.
+- Triage build issues - file issues for known flaky builds or bugs, and either fix or find someone to fix any master build breakages.
+- During GitHub issue triage, apply all applicable ([labels](https://github.com/backstage/backstage/labels)) to each new issue. Labels are extremely useful for future issue follow up. Which labels to apply is somewhat subjective so just use your best judgment. A few of the most important labels that are not self explanatory are:
+  - good first issue: Mark any issue that can reasonably be accomplished by a new contributor with this label.
+  - help wanted: Unless it is immediately obvious that someone is going to work on an issue (and if so assign it), mark it help wanted.
+- Make sure that ongoing PRs are moving forward at the right pace or closing them.
+- Participate when called upon in the security release process. Note that although this should be a rare occurrence, if a serious vulnerability is found, the process may take up to several full days of work to implement. This reality should be taken into account when discussing time commitment obligations with employers.
+- In general, continue to be willing to spend at least 25% of one's time working on Backstage (~1.25 business days per week).
+- We currently maintain an "on-call" rotation within the maintainers. Each on-call is 1 week. Although all maintainers are welcome to perform all of the above tasks, it is the on-call maintainer's responsibility to triage incoming issues/questions and marshal ongoing work forward. To reiterate, it is not the responsibility of the on-call maintainer to answer all questions and do all reviews, but it is their responsibility to make sure that everything is being actively covered by someone.
 
-- nominee's first and last name,
-- nominee's email address and GitHub user name,
-- an explanation of why the nominee should be a maintainer,
-- a list of links to non-trivial pull requests (top 10) authored by the nominee.
+# When does a maintainer lose maintainer status
 
-Maintainers can be removed by a 2/3 majority vote.
+If a maintainer is no longer interested or cannot perform the maintainer duties listed above, they should volunteer to be moved to emeritus status. In extreme cases this can also occur by a vote of the sponsors and maintainers per the voting process below.
 
-## Approving PRs
+# Conflict resolution and voting
 
-PRs may be merged after receiving at least one approval from a maintainer.
+In general, we prefer that technical issues and maintainer membership are amicably worked out between the persons involved. If a dispute cannot be decided independently, the sponsors and maintainers can be called in to decide an issue. If the sponsors and maintainers themselves cannot decide an issue, the issue will be resolved by voting. The voting process is a simple majority in which each sponsor receives two votes and each maintainer receives one vote.
 
-## GitHub Project Administration
+# Adding new projects to the Backstage GitHub organization
 
-Maintainers will be added to the collaborators list of the Backstage repository with "Write" access.
-
-## Changes in Governance
-
-All changes in Governance require a 2/3 majority vote.
-
-## Other Changes
-
-Unless specified above, all other changes to the project require a 2/3 majority vote.
-Additionally, any maintainer may request that any change require a 2/3 majority vote.
+New projects will be added to the Backstage organization via GitHub issue discussion in one of the existing projects in the organization. Once sufficient discussion has taken place (~3-5 business days but depending on the volume of conversation), the maintainers of the project where the issue was opened (since different projects in the organization may have different maintainers) will decide whether the new project should be added. See the section above on voting if the maintainers cannot easily decide.

MAINTAINERS.md

@@ -1,21 +0,0 @@
-# Maintainers
-
-- See [CONTRIBUTING.md](CONTRIBUTING.md) for general contribution guidelines.
-
-## Current Maintainers 🏓
-
-- Stefan Ålund - Spotify (GitHub: @stefanalund, Discord: @stalund)
-- Patrik Oldsberg - Spotify (GitHub: @Rugvip, Discord: @Rugvip)
-- Fredrik Adelöw - Spotify (GitHub: @freben, Discord: @freben)
-- Ben Lambert - Spotify (GitHub: @benjdlambert, Discord: @blam)
-
-## Plugin maintainers 🧩
-
-Teams and individuals that maintain a plugin (or another non-core module of the code) can get write access to that part of the repo using CODEOWNERS.
-
-## Hall of Fame 👏
-
-People that have made significant contributions to the project and earned write access:
-
-- Andrew Thauer - Wealthsimple (GitHub: @andrewthauer)
-- Oliver Sand - SDA SE (GitHub: @Fox32)

OWNERS.md

@@ -0,0 +1,24 @@
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for general contribution guidelines.
+- See [GOVERNANCE.md](GOVERNANCE.md) for governance guidelines and responsibilities.
+
+This page lists all active sponsors and maintainers.
+
+# Sponsors
+
+- Niklas Gustavsson ([protocol7](https://github.com/protocol7)) (ngn@spotify.com)
+- Dave Zolotusky ([dzolotusky](https://github.com/dzolotusky)) (dzolo@spotify.com)
+- Lee Mills ([leemills83](https://github.com/leemills83)) (leem@spotify.com)
+
+# Maintainers
+
+- Patrik Oldsberg ([rugvip](https://github.com/rugvip)) (Discord: @Rugvip)
+- Fredrik Adelöw ([freben](https://github.com/freben)) (Discord: @freben)
+- Ben Lambert ([benjdlambert](https://github.com/benjdlambert)) (Discord: @blam)
+- Stefan Ålund ([stefanalund](https://github.com/stefanalund)) (Discord: @stalund)
+
+# Friends of Backstage
+
+People that have made significant contributions to the project and earned write access.
+
+- Andrew Thauer - Wealthsimple (GitHub: [andrewthauer](https://github.com/andrewthauer))
+- Oliver Sand - SDA SE (GitHub: [Fox32](https://github.com/Fox32))

app-config.yaml

@@ -38,7 +38,7 @@ proxy:
     headers:
       Authorization:
         $env: TRAVISCI_AUTH_TOKEN
-      travis-api-version: 3
+      travis-api-version: '3'
 
   '/newrelic/apm/api':
     target: https://api.newrelic.com/v2
@@ -46,22 +46,45 @@ proxy:
       X-Api-Key:
         $env: NEW_RELIC_REST_API_KEY
 
+  '/pagerduty':
+    target: https://api.pagerduty.com
+    headers:
+      Authorization:
+        $env: PAGERDUTY_TOKEN
+
+  '/buildkite/api':
+    target: https://api.buildkite.com/v2/
+    headers:
+      Authorization:
+        $env: BUILDKITE_TOKEN
+
+  '/sentry/api':
+    target: https://sentry.io/api/
+    allowedMethods: ['GET']
+    headers:
+      Authorization:
+        $env: SENTRY_TOKEN
+
 organization:
   name: My Company
 
+# Reference documentation http://backstage.io/docs/features/techdocs/configuration
 techdocs:
-  storageUrl: http://localhost:7000/api/techdocs/static/docs
   requestUrl: http://localhost:7000/api/techdocs
+  storageUrl: http://localhost:7000/api/techdocs/static/docs
+  builder: 'local' # Alternatives - 'external'
   generators:
-    techdocs: 'docker'
+    techdocs: 'docker' # Alternatives - 'local'
+  publisher:
+    type: 'local' # Alternatives - 'googleGcs'. Read documentation for using alternatives.
 
 sentry:
   organization: my-company
 
 rollbar:
   organization: my-company
-  accountToken:
-    $env: ROLLBAR_ACCOUNT_TOKEN
+  # NOTE: The rollbar-backend & accountToken key may be deprecated in the future (replaced by a proxy config)
+  accountToken: my-rollbar-account-token
 
 lighthouse:
   baseUrl: http://localhost:3003
@@ -114,7 +137,7 @@ catalog:
             $env: GITHUB_TOKEN
         #### Example for how to add your GitHub Enterprise instance using the API:
         # - target: https://ghe.example.net
-        #   apiBaseUrl: https://ghe.example.net/api/v3
+        #   apiBaseUrl: https://ghe.example.net/api
         #   token:
         #     $env: GHE_TOKEN
     ldapOrg:
@@ -134,6 +157,19 @@ catalog:
       #       dn: ou=access,ou=groups,ou=example,dc=example,dc=net
       #       options:
       #         filter: (&(objectClass=some-group-class)(!(groupType=email)))
+    microsoftGraphOrg:
+      ### Example for how to add your Microsoft Graph tenant
+      #providers:
+      #  - target: https://graph.microsoft.com/v1.0
+      #    authority: https://login.microsoftonline.com
+      #    tenantId:
+      #      $env: MICROSOFT_GRAPH_TENANT_ID
+      #    clientId:
+      #      $env: MICROSOFT_GRAPH_CLIENT_ID
+      #    clientSecret:
+      #      $env: MICROSOFT_GRAPH_CLIENT_SECRET_TOKEN
+      #    userFilter: accountEnabled eq true and userType eq 'member'
+      #    groupFilter: securityEnabled eq false and mailEnabled eq true and groupTypes/any(c:c+eq+'Unified')
 
   locations:
     # Backstage example components
@@ -170,8 +206,11 @@ scaffolder:
     api:
       token:
         $env: AZURE_TOKEN
-
 auth:
+  environment: development
+  ### Providing an auth.session.secret will enable session support in the auth-backend
+  # session:
+  #   secret: custom session secret
   providers:
     google:
       development:
@@ -216,6 +255,20 @@ auth:
           $env: AUTH_OAUTH2_AUTH_URL
         tokenUrl:
           $env: AUTH_OAUTH2_TOKEN_URL
+    oidc:
+      development:
+        metadataUrl:
+          $env: AUTH_OIDC_METADATA_URL
+        clientId:
+          $env: AUTH_OIDC_CLIENT_ID
+        clientSecret:
+          $env: AUTH_OIDC_CLIENT_SECRET
+        authorizationUrl:
+          $env: AUTH_OIDC_AUTH_URL
+        tokenUrl:
+          $env: AUTH_OIDC_TOKEN_URL
+        tokenSignedResponseAlg:
+          $env: AUTH_OIDC_TOKEN_SIGNED_RESPONSE_ALG
     auth0:
       development:
         clientId:
@@ -255,6 +308,9 @@ costInsights:
     bigQuery:
       name: BigQuery
       icon: search
+    events:
+      name: Events
+      icon: data
   metrics:
     DAU:
       name: Daily Active Users
@@ -264,10 +320,12 @@ costInsights:
 homepage:
   clocks:
     - label: UTC
-      timzone: UTC
+      timezone: UTC
     - label: NYC
       timezone: 'America/New_York'
     - label: STO
       timezone: 'Europe/Stockholm'
     - label: TYO
       timezone: 'Asia/Tokyo'
+pagerduty:
+  eventsBaseUrl: 'https://events.pagerduty.com/v2'

contrib/chart/backstage/README.md

@@ -7,7 +7,7 @@ This folder contains Helm charts that can easily create a Kubernetes deployment
 These charts depend on the `nginx-ingress` controller being present in the cluster. If it's not already installed you
 can run:
 
-```
+```shell
 helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
 helm install nginx-ingress ingress-nginx/ingress-nginx
 ```
@@ -16,7 +16,7 @@ helm install nginx-ingress ingress-nginx/ingress-nginx
 
 After choosing a DNS name where backstage will be hosted create a yaml file for your custom configuration.
 
-```
+```yaml
 appConfig:
   app:
     baseUrl: https://backstage.mydomain.com
@@ -30,12 +30,11 @@ appConfig:
   techdocs:
     storageUrl: https://backstage.mydomain.com/api/techdocs/static/docs
     requestUrl: https://backstage.mydomain.com/api/techdocs
-
 ```
 
 Then use it to run:
 
-```
+```shell
 git clone https://github.com/backstage/backstage.git
 cd contrib/chart/backstage
 helm dependency update
@@ -54,7 +53,7 @@ After a few minutes Backstage should be up and running in your cluster under the
 
 Make sure to create the appropriate DNS entry in your infrastructure. To find the public IP address run:
 
-```bash
+```shell
 $ kubectl get ingress
 NAME                HOSTS   ADDRESS         PORTS   AGE
 backstage-ingress   *       123.1.2.3       80      17m
@@ -74,10 +73,10 @@ These charts can install or reuse a `clusterIssuer` to generate certificates for
 
 To enable it you need to provide a valid email address in the chart's values:
 
-```
+```yaml
 issuer:
   email: me@example.com
-  clusterIssuer: "letsencrypt-prod"
+  clusterIssuer: 'letsencrypt-prod'
 ```
 
 By default, the charts use `letsencrypt-staging` so in the above example we instruct helm to use the production issuer
@@ -92,7 +91,7 @@ Configuring a connection to an existing PostgreSQL instance is possible through
 
 First create a yaml file with the configuration you want to override, for example `backstage-prod.yaml`:
 
-```bash
+```yaml
 postgresql:
   enabled: false
 
@@ -122,12 +121,11 @@ lighthouse:
       user: <pg user>
       password: <password>
       database: lighthouse_audit_service
-
 ```
 
 For the CA, create a `configMap` named `<release name>-<chart name>-postgres-ca` with a file called `ca.crt`:
 
-```
+```shell
 kubectl create configmap my-company-backstage-postgres-ca --from-file=ca.crt"
 ```
 
@@ -135,7 +133,7 @@ kubectl create configmap my-company-backstage-postgres-ca --from-file=ca.crt"
 
 Now install the helm chart:
 
-```
+```shell
 cd contrib/chart/backstage
 helm install -f backstage-prod.yaml my-backstage .
 ```
@@ -144,7 +142,7 @@ helm install -f backstage-prod.yaml my-backstage .
 
 The docker images used for the deployment can be configured through the charts values:
 
-```
+```yaml
 frontend:
   image:
     repository: <image-name>
@@ -165,7 +163,7 @@ lighthouse:
 
 Create a docker-registry secret
 
-```
+```shell
 kubectl create secret docker-registry <docker_registry_secret_name> # args
 ```
 
@@ -181,7 +179,7 @@ dockerRegistrySecretName: <docker_registry_secret_name>
 
 To install the charts a specific namespace use `--namespace <ns>`:
 
-```
+```shell
 helm install -f my_values.yaml --namespace demos backstage .
 ```
 
@@ -189,7 +187,7 @@ helm install -f my_values.yaml --namespace demos backstage .
 
 To deploy backstage with the pre-loaded demo data disable `backend.demoData`:
 
-```
+```shell
 helm install -f my_values.yaml --set backend.demoData=false backstage .
 ```
 
@@ -244,7 +242,7 @@ This error happens in the backend when it tries to connect to the configured Pos
 
 To uninstall Backstage simply run:
 
-```
+```shell
 RELEASE_NAME=<release-name> # use `helm list` to find out the name
 helm uninstall ${RELEASE_NAME}
 kubectl delete pvc data-${RELEASE_NAME}-postgresql-0

contrib/chart/backstage/templates/backend-secret.yaml

@@ -20,4 +20,5 @@ stringData:
   AZURE_TOKEN: {{ .Values.auth.azure.api.token }}
   NEW_RELIC_REST_API_KEY: {{ .Values.auth.newRelicRestApiKey }}
   TRAVISCI_AUTH_TOKEN: {{ .Values.auth.travisciAuthToken }}
+  PAGERDUTY_TOKEN: {{ .Values.auth.pagerdutyToken }}
 {{- end }}

contrib/chart/backstage/values.yaml

@@ -250,3 +250,4 @@ auth:
   gitlabToken: g
   newRelicRestApiKey: r
   travisciAuthToken: fake-travis-ci-auth-token
+  pagerdutyToken: h

contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md

@@ -3,7 +3,7 @@
 ExampleComponent.tsx reference
 
 ```tsx
-import React, { FC } from 'react';
+import React from 'react';
 import { Typography, Grid } from '@material-ui/core';
 import {
   InfoCard,
@@ -18,7 +18,7 @@ import {
 import { useApi } from '@backstage/core-api';
 import ExampleFetchComponent from '../ExampleFetchComponent';
 
-const ExampleComponent: FC<{}> = () => {
+const ExampleComponent = () => {
   const identityApi = useApi(identityApiRef);
   const userId = identityApi.getUserId();
   const profile = identityApi.getProfile();

contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md

@@ -3,7 +3,7 @@
 ExampleFetchComponent.tsx reference
 
 ```tsx
-import React, { FC } from 'react';
+import React from 'react';
 import { useAsync } from 'react-use';
 import Alert from '@material-ui/lab/Alert';
 import {
@@ -57,7 +57,7 @@ type DenseTableProps = {
   viewer: Viewer;
 };
 
-export const DenseTable: FC<DenseTableProps> = ({ viewer }) => {
+export const DenseTable = ({ viewer }: DenseTableProps) => {
   const columns: TableColumn[] = [
     { title: 'Name', field: 'name' },
     { title: 'Created', field: 'createdAt' },
@@ -76,7 +76,7 @@ export const DenseTable: FC<DenseTableProps> = ({ viewer }) => {
   );
 };
 
-const ExampleFetchComponent: FC<{}> = () => {
+const ExampleFetchComponent = () => {
   const auth = useApi(githubAuthApiRef);
 
   const { value, loading, error } = useAsync(async (): Promise<any> => {

docs/FAQ.md

@@ -48,10 +48,9 @@ source candidates. (And we'll probably end up writing some brand new ones, too.)
 ### What's the roadmap for Backstage?
 
 We envision three phases, which you can learn about in
-[our project roadmap](https://github.com/backstage/backstage#project-roadmap).
-Even though the open source version of Backstage is relatively new compared to
-our internal version, we have already begun work on various aspects of all three
-phases. Looking at the
+[our project roadmap](overview/roadmap.md). Even though the open source version
+of Backstage is relatively new compared to our internal version, we have already
+begun work on various aspects of all three phases. Looking at the
 [milestones for active issues](https://github.com/backstage/backstage/milestones)
 will also give you a sense of our progress.
 
@@ -115,10 +114,65 @@ type of content. Plugins all use a common set of platform APIs and reusable UI
 components. Plugins can fetch data either from the backend or an API exposed
 through the proxy.
 
-Learn more about
-[the different components](https://github.com/backstage/backstage#overview) that
+Learn more about [the different components](overview/what-is-backstage.md) that
 make up Backstage.
 
+### How do I keep my Backstage app up to date?
+
+In many ways one can view Backstage as a library rather than an application or
+service. The `@backstage/create-app` tool that is used to create your own
+Backstage app is similar to
+[`create-react-app`](https://github.com/facebook/create-react-app) in that it
+gives you a starting point. The code you get is meant to be evolved, and most of
+the functionality you get out of the box is brought in via npm dependencies.
+Keeping your app up to date generally means keeping your dependencies up to
+date. The Backstage CLI provides a command to help you with that. Simply run
+`yarn backstage-cli versions:bump` at the root of your repo, and the latest
+versions of all Backstage packages will be installed.
+
+While staying up to date with new releases and changes will keep your app up to
+date, it can often be convenient to use the changes done to the
+`@backstage/create-app` template as another method to stay up to date. For that
+purpose, any changes done to the template are documented along with upgrade
+instructions in the
+[changelog](https://github.com/backstage/backstage/blob/master/packages/create-app/CHANGELOG.md)
+of the `@backstage/create-app` package.
+
+### Why can't I dynamically install plugins without modifications the app?
+
+This decision is part of the core architecture and development flow of
+Backstage. Plugins have a lot of freedom in what they provide and how they are
+integrated into the app, and it would therefore add a lot of complexity to allow
+plugins to be integrated via configuration the same way as they can be
+integrated with code.
+
+By bundling all plugins and their dependencies into one app bundle it is also
+possible to do significant optimizations to the app load time by allowing
+plugins to share dependencies between each other when possible. This contributes
+to Backstage being fast, which is an important part of the user and developer
+experience.
+
+### Why are there no published Docker images or helm charts for Backstage?
+
+As mentioned above, Backstage is not a packaged service that you can use out of
+the box. In order to get started with Backstage you need to use the
+`@backstage/create-app` package to create and customize your own Backstage app.
+
+In order to build a Docker image from your own app, you can use the
+`yarn build-image` command which is included out of the box in the app template.
+By default this image will bundle up both the frontend and the backend into a
+single image that you can deploy using your favorite tooling.
+
+There are also some examples that can help you deploy Backstage to kubernetes in
+the
+[contrib](https://github.com/backstage/backstage/tree/master/contrib/kubernetes)
+folder.
+
+It is possible that example images will be provided in the future, which can be
+used to quickly try out a small subset of the functionality of Backstage, but
+these would not be able to provide much more functionality on top of what you
+can see on a demo site.
+
 ### Do I have to write plugins in TypeScript?
 
 No, you can use JavaScript if you prefer. We want to keep the Backstage core
@@ -126,17 +180,17 @@ APIs in TypeScript, but aren't forcing it on individual plugins.
 
 ### How do I find out if a plugin already exists?
 
-Before you write a plugin,
+You can browse and search for all available plugins in the
+[Plugin Marketplace](https://backstage.io/plugins).
+
+If you can't find it in the marketplace, before you write a plugin
 [search the plugin issues](https://github.com/backstage/backstage/issues?q=is%3Aissue+label%3Aplugin+)
-to see if it already exists or is in the works. If no one's thought of it yet,
-great! Open a new issue as
+to see if is in the works. If no one's thought of it yet, great! Open a new
+issue as
 [a plugin suggestion](https://github.com/backstage/backstage/issues/new/choose)
 and describe what your plugin will do. This will help coordinate our
 contributors' efforts and avoid duplicating existing functionality.
 
-You can browse and search for all available plugins in the
-[Plugin Marketplace](https://backstage.io/plugins).
-
 ### Which plugin is used the most at Spotify?
 
 By far, our most-used plugin is our TechDocs plugin, which we use for creating
@@ -182,6 +236,10 @@ comes to [deployment](https://backstage.io/docs/getting-started/deployment-k8s),
 the system integrator (typically, the infrastructure team in your organization)
 maintains Backstage in your own environment.
 
+For more information, see our
+[Owners](https://github.com/backstage/backstage/blob/master/OWNERS.md) and
+[Governance](https://github.com/backstage/backstage/blob/master/GOVERNANCE.md).
+
 ### Does Spotify provide a managed version of Backstage?
 
 No, this is not a service offering. We build the piece of software, and someone
@@ -215,14 +273,14 @@ data is shared with.
 Yes. The core frontend framework could be used for building any large-scale web
 application where (1) multiple teams are building separate parts of the app, and
 (2) you want the overall experience to be consistent. That being said, in
-[Phase 2](https://github.com/backstage/backstage#project-roadmap) of the project
-we will add features that are needed for developer portals and systems for
-managing software ecosystems. Our ambition will be to keep Backstage modular.
+[Phase 2](overview/roadmap.md) of the project we will add features that are
+needed for developer portals and systems for managing software ecosystems. Our
+ambition will be to keep Backstage modular.
 
 ### How can I get involved?
 
 Jump right in! Come help us fix some of the
-[early bugs and first issues](https://github.com/backstage/backstage/labels/good%20first%20issue)
+[early bugs and good first issues](https://github.com/backstage/backstage/contribute)
 or reach [a new milestone](https://github.com/backstage/backstage/milestones).
 Or write an open source plugin for Backstage, like this
 [Lighthouse plugin](https://github.com/backstage/backstage/tree/master/plugins/lighthouse).

docs/api/utility-apis.md

@@ -11,7 +11,7 @@ possible residing within the plugin itself and its backend APIs. There will
 however always be a need for plugins to communicate outside of its boundaries,
 both with other plugins and the app itself.
 
-Backstage provides two primary methods for plugins to communication across their
+Backstage provides two primary methods for plugins to communicate across their
 boundaries in client-side code. The first one being the `createPlugin` API and
 the registration hooks passed to the `register` method, and the second one being
 Utility APIs. While the `createPlugin` API is focused on the initialization
@@ -33,10 +33,10 @@ hook exported by `@backstage/core`, or the `withApis` HOC if you prefer class
 components. For example, the `ErrorApi` can be accessed like this:
 
 ```tsx
-import React, { FC } from 'react';
+import React from 'react';
 import { useApi, errorApiRef } from '@backstage/core';
 
-export const MyComponent: FC<{}> = () => {
+export const MyComponent = () => {
   const errorApi = useApi(errorApiRef);
 
   // Signal to the app that something went wrong, and display the error to the user.
@@ -195,8 +195,8 @@ interface for the API, and create an `ApiRef` using `createApiRef` exported from
 `@backstage/core`. Also be sure to provide at least one implementation of the
 API, and to declare a default factory for the API in `createPlugin`.
 
-Custom Utility APIs can be either public or private, which it is up to the
-plugin to choose. Private APIs do not expose an external API surface, and it's
+Custom Utility APIs can be either public or private, which is up to the plugin
+to choose. Private APIs do not expose an external API surface, and it's
 therefore possible to make breaking changes to the API without affecting other
 users of the plugin. If an API is made public however, it opens up for other
 plugins to make use of the API, and it also makes it possible for users for your
@@ -243,7 +243,7 @@ The figure below shows the relationship between
 The current method for connecting Utility API providers and consumers is via the
 React tree using an `ApiProvider`, which is added to the `AppProvider` of the
 `App`. In the future there may potentially be more ways to do this, in ways that
-are not tied to react. A design goal of the Utility APIs was to not have them
+are not tied to React. A design goal of the Utility APIs was to not have them
 directly tied to React.
 
 The indirection provided by Utility APIs also makes it straightforward to test

docs/architecture-decisions/adr005-catalog-core-entities.md

@@ -58,7 +58,7 @@ discover existing functionality in the ecosystem.
 APIs are implemented by components and make their boundaries explicit. They
 might be defined using an RPC IDL (e.g. in Protobuf, GraphQL or similar), a data
 schema (e.g. in Avro, TFRecord or similar), or as code interfaces (e.g.
-framework APIs in Swift, Kotlin, Java, C++, Typescript etc). In any case, APIs
+framework APIs in Swift, Kotlin, Java, C++, TypeScript etc). In any case, APIs
 exposed by components need to be in a known machine-readable format so we can
 build further tooling and analysis on top.
 

docs/architecture-decisions/adr006-avoid-react-fc.md

@@ -6,7 +6,7 @@ description: Architecture Decision Record (ADR) log on Avoid React.FC and React.
 
 ## Context
 
-Facebook has removed `React.FC` from their base template for a Typescript
+Facebook has removed `React.FC` from their base template for a TypeScript
 project. The reason for this was that it was found to be an unnecessary feature
 with next to no benefits in combination with a few downsides.
 

docs/auth/auth-backend-classes.md

@@ -6,57 +6,71 @@ description: Documentation on Auth backend classes
 
 ## How Does Authentication Work?
 
-The Backstage application can use various authentication providers for
-authentication. A provider has to implement an `AuthProviderRouteHandlers`
-interface for handling authentication. This interface consists of four methods.
-Each of these methods is hosted at an endpoint `/auth/[provider]/method`, where
-`method` performs a certain operation as follows:
+The Backstage application can use various external authentication providers for
+authentication. An external provider is wrapped using an
+`AuthProviderRouteHandlers` interface for handling authentication. This
+interface consists of four methods. Each of these methods is hosted at an
+endpoint (by default) `/api/auth/[provider]/method`, where `method` performs a
+certain operation as follows:
 
 ```
-  /auth/[provider]/start -> start
-  /auth/[provider]/handler/frame -> frameHandler
-  /auth/[provider]/refresh -> refresh
-  /auth/[provider]/logout -> logout
+  /auth/[provider]/start -> Initiate a login from the web page
+  /auth/[provider]/handler/frame -> Handle a finished authentication operation
+  /auth/[provider]/refresh -> Refresh the validity of a login
+  /auth/[provider]/logout -> Log out a logged-in user
 ```
 
-For more information on how these methods are used and for which purpose, refer
-to the [OAuth documentation](oauth.md).
+The flow is as follows:
 
-For details on the parameters, input and output conditions for each method,
-refer to the type documentation under
-`plugins/auth-backend/src/providers/types.ts`.
+1. A user attempts to sign in.
+2. A popup window is opened, pointing to the `auth` endpoint. That endpoint does
+   initial preparations and then re-directs the user to an external
+   authenticator, still inside the popup.
+3. The authenticator validates the user and returns the result of the validation
+   (success OR failure), to the wrapper's endpoint (`handler/frame`).
+4. The `handler/frame` rendered b´webpage will issue the appropriate response to
+   the webpage that opened the popup window, and the popup is closed.
+5. The user signs out by clicking on a UI interface and the webpage makes a
+   request to logout the user.
 
 There are currently two different classes for two authentication mechanisms that
 implement this interface: an `OAuthAdapter` for [OAuth](https://oauth.net/2/)
 based mechanisms and a `SAMLAuthProvider` for
-[SAML](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html)
-based mechanisms.
+[SAML](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html).
 
-### OAuth mechanisms
+If you do not have an `OAuth2` or `SAML` based authentication provider, look in
+the section [below](#implementing-your-own-auth-wrapper).
+
+### OAuth Mechanisms
+
+For more information on how these methods are used and for which purpose, refer
+to the [OAuth documentation](oauth.md).
 
 Currently OAuth is assumed to be the de facto authentication mechanism for
 Backstage based applications.
 
 Backstage comes with a "batteries-included" set of supported commonly used OAuth
-providers: Okta, GitHub, Google, GitLab, and a generic OAuth2 provider.
+providers: Okta, GitHub, Google, GitLab, and a generic OAuth2 provider. For a
+list of available providers, look at the available wrappers in
+`backstage/plugins/auth-backend/src/providers/`.
 
-All of these use the authorization flow of OAuth2 to implement authentication.
+All of these use the **authorization flow** of OAuth2 to implement
+authentication.
 
-If your authentication provider is any of the above mentioned (except generic
-OAuth2) providers, you can configure them by setting the right variables in
-`app-config.yaml` under the `auth` section.
+If your authentication provider is any of the above mentioned providers, you can
+configure them by setting the right variables in `app-config.yaml` under the
+`auth` section.
 
 ### Configuration
 
 Each authentication provider (except SAML) needs five parameters: an OAuth
-client ID, a client secret, an authorization endpoint and a token endpoint, and
-an app origin. The app origin is the URL at which the frontend of the
-application is hosted, and it is read from the `app.baseUrl` config. This is
-required because the application opens a popup window to perform the
-authentication, and once the flow is completed, the popup window sends a
-`postMessage` to the frontend application to indicate the result of the
-operation. Also this URL is used to verify that authentication requests are
-coming from only this endpoint.
+client ID, a client secret, an authorization endpoint, a token endpoint, and an
+app origin. The app origin is the URL at which the frontend of the application
+is hosted, and it is read from the `app.baseUrl` config. This is required
+because the application opens a popup window to perform the authentication, and
+once the flow is completed, the popup window sends a `postMessage` to the
+frontend application to indicate the result of the operation. Also this URL is
+used to verify that authentication requests are coming from only this endpoint.
 
 These values are configured via the `app-config.yaml` present in the root of
 your app folder.
@@ -85,20 +99,60 @@ auth:
             ...
 ```
 
-## Technical Notes
+## Implementing Your Own Auth Wrapper
 
-### OAuthEnvironmentHandler
+The core interface of any auth wrapper is the `AuthProviderRouteHandlers`
+interface. This interface has four methods corresponding to the API described in
+the initial section. Any auth wrapper will have to implement this interface.
 
-The concept of an "env" is core to the way the auth backend works. It uses an
+When initiating a login, a pop-up window is created by the frontend, to allow
+the user to initiate a login. This login request is done to the `/start`
+endpoint which is handled by the `start` method.
+
+The `start` method re-directs to the external auth provider who authenticates
+the request and re-directs the request to the `/frame/handler` endpoint, which
+is handled by the `frameHandler` method.
+
+The `frameHandler` returns an HTML response, containing a script that does a
+`postMessage` to the frontend's window, containing the result of the request.
+The `WebMessageResponse` type is the message sent by the `postMessage` to the
+frontend.
+
+A `postMessageResponse` utility function wraps the logic of generating a
+`postMessage` response that ensures that CORS is successfully handled. This
+function takes an `express.Response`, a `WebMessageResponse` and the URL of the
+frontend (`appOrigin`) as parameters and return an HTML page with the script and
+the message.
+
+### OAuth Wrapping Interfaces.
+
+Each OAuth external provider is supported by a corresponding
+[Passport](https://github.com/jaredhanson/passport) strategy. For a generic
+OAuth2 provider, passport has a `passport-oauth2` strategy. The strategy class
+handles the implementation details of working with each provider.
+
+Each strategy is wrapped by an `OAuthHandlers` interface.
+
+This interface cannot be directly used as an Express HTTP request handler. To do
+so, `OAuthHandlers` are wrapped in an `OAuthAdapter`, which implements the
+`AuthProviderRouterHandlers` interface.
+
+#### Env
+
+The concept of an `env` is core to the way the auth backend works. It uses an
 `env` query parameter to identify the environment in which the application is
-running (`development`, `staging`, `production`, etc). Each runtime can support
-multiple environments at the same time and the right handler for each request is
-identified and dispatched to based on the `env` parameter. All
-`AuthProviderRouteHandlers` are wrapped within an `OAuthEnvironmentHandler`.
+running (`development`, `staging`, `production`, etc). Each runtime can
+simultaneously support multiple environments at the same time and the right
+handler for each request is identified and dispatched to, based on the `env`
+parameter.
 
-To instantiate multiple OAuth providers for different environments, use
+`OAuthEnvironmentHandler` is a utility wrapper for an `OAuthHandlers` that
+implements the `AuthProviderRouteHandlers` interface while supporting multiple
+`env`s.
+
+To instantiate OAuth providers (the same but for different environments), use
 `OAuthEnvironmentHandler.mapConfig`. It's a helper to iterate over a
-configuration object that is a map of environment to configurations. See one of
+configuration object that is a map of environments to configurations. See one of
 the existing OAuth providers for an example of how it is used.
 
 Given the following configuration:
@@ -113,13 +167,18 @@ production:
 ```
 
 The `OAuthEnvironmentHandler.mapConfig(config, envConfig => ...)` call will
-split the `config` by the top level `development` and `production` keys, and
-pass on each block as `envConfig`.
+split the config by the top level `development` and `production` keys, and pass
+on each block as `envConfig`.
 
-For a list of currently available providers, look in the `factories` module
-located in `plugins/auth-backend/src/providers/factories.ts`
+For convenience, the `AuthProviderFactory` is a factory function that has to be
+implemented which can then generate a `AuthProviderRouteHandlers` for a given
+provider.
 
-### OAuth2 provider
+All of the supported providers provide an `AuthProviderFactory` that returns an
+`OAuthEnvironmentHandler`, capable of handling authentication for multiple
+environments.
+
+### OAuth2 Provider
 
 The `oauth2` provider abstracts a generic **OAuth2 + OIDC** based authentication
 provider. What this means is that after the application has been given

docs/auth/index.md

@@ -93,6 +93,6 @@ sign-in methods.
 More details are provided in dedicated sections of the documentation.
 
 - [OAuth](./oauth.md): Description of the generic OAuth flow implemented by the
-  [auth-backend](../../plugins/auth-backend).
+  [auth-backend](https://github.com/backstage/backstage/tree/master/plugins/auth-backend).
 - [Glossary](./glossary.md): Glossary of some common terms related to the auth
   flows.

docs/conf/defining.md

@@ -4,16 +4,115 @@ title: Defining Configuration for your Plugin
 description: Documentation on Defining Configuration for your Plugin
 ---
 
-There is currently no tooling support or helpers for defining plugin
-configuration. But it's on the roadmap.
+Configuration in Backstage is organized via a configuration schema, which in
+turn is defined using a superset of
+[JSON Schema Draft-07](https://json-schema.org/specification-links.html#draft-7).
+Each plugin or package within a Backstage app can contribute to the schema,
+which during validation is stitched together into a single schema.
 
-Meanwhile, document the config values that you are reading in your plugin
-README.
+## Schema Collection and Definition
 
-## Format
+Schemas are collected from all packages and dependencies in each repo that are a
+part of the Backstage ecosystem, including transitive dependencies. The current
+definition of "part of the ecosystem" is that a package has at least one
+dependency in the `@backstage` namespace, but this is subject to change.
+
+Each package is searched for a schema at a single point of entry, a top-level
+`"configSchema"` field in `package.json`. The field can either contain an
+inlined JSON schema, or a relative path to a schema file. Supported schema file
+formats are `.json` or `.d.ts`.
+
+> When defining a schema file, be sure to include the file in your
+> `package.json` > `"files"` field as well!
+
+TypeScript configuration schema files should export a single `Config` type, for
+example:
+
+```ts
+export interface Config {
+  app: {
+    /**
+     * Frontend root URL
+     * @visibility frontend
+     */
+    baseUrl: string;
+  };
+}
+```
+
+Separate `.json` schema files can use a top-level
+`"$schema": "https://backstage.io/schema/config-v1"` declaration in order to
+receive schema validation and autocompletion. For example:
+
+```json
+{
+  "$schema": "https://backstage.io/schema/config-v1",
+  "type": "object",
+  "properties": {
+    "app": {
+      "type": "object",
+      "properties": {
+        "baseUrl": {
+          "type": "string",
+          "description": "Frontend root URL",
+          "visibility": "frontend"
+        }
+      },
+      "required": ["baseUrl"]
+    },
+    "required": ["app"]
+  }
+}
+```
+
+## Visibility
+
+The `https://backstage.io/schema/config-v1` meta schema is a superset of JSON
+Schema Draft 07. The single addition is a custom `visibility` keyword, which is
+used to indicate whether the given config value should be visible in the
+frontend or not. The possible values are `frontend`, `backend`, and `secret`,
+where `backend` is the default. A visibility of `secret` has the same scope at
+runtime, but it will be treated with more care in certain contexts, and defining
+both `frontend` and `secret` for the same value in two different schemas will
+result in an error during schema merging.
+
+The visibility only applies to the direct parent of where the keyword is placed
+in the schema. For example, if you set the visibility to `frontend` for a subset
+of the schema with `type: "object"`, but none of the descendants, only an empty
+object will be available in the frontend. The full ancestry does not need to
+have correctly defined visibilities however, so it is enough to only for example
+declare the visibility of a leaf node of `type: "string"`.
+
+| `visibility` |                                                                    |
+| ------------ | ------------------------------------------------------------------ |
+| `frontend`   | Visible in frontend and backend                                    |
+| `backend`    | (Default) Only in backend                                          |
+| `secret`     | Only in backend and may be excluded from logs for security reasons |
+
+## Validation
+
+Schemas can be validated using the `backstage-cli config:check` command. If you
+want to validate anything else than the default `app-config.yaml`, be sure to
+pass in all of the configuration files as `--config <path>` options as well.
+
+To validate and examine the frontend configuration, use the
+`backstage-cli config:print --frontend` command. Just like for validation you
+may need to pass in all files using one or multiple `--config <path>` options.
+
+## Guidelines
+
+> Make limited use of static configuration. The first question to ask is whether
+> a particular option actually needs to be static configuration, or if it might
+> just as well be a TypeScript API. In general, options that you want to be able
+> to change for different deployment environments should be static
+> configuration, while it should otherwise be avoided.
 
 When defining configuration for your plugin, keep keys camelCased and stick to
-existing casing conventions such as `baseUrl`.
+existing casing conventions such as `baseUrl` rather than `baseURL`.
 
 It is also usually best to prefer objects over arrays, as it makes it possible
 to override individual values using separate files or environment variables.
+
+Avoid creating new top-level fields as much as possible. Either place your
+configuration within an existing known top-level block, or create a single new
+one using e.g. the name of the product that the plugin integrates.

docs/conf/index.md

@@ -28,11 +28,25 @@ development or small tweaks to be able to reuse deployment artifacts in
 different environments.
 
 The configuration is shared between the frontend and backend, meaning that
-values that are common between the two only needs to be defined once. Such as
-the `backend.baseUrl`.
+values that are common between the two only need to be defined once. Such as the
+`backend.baseUrl`.
 
 For more details, see [Writing Configuration](./writing.md).
 
+## Configuration Schema
+
+The configuration is validated using JSON Schema definitions. Each plugin and
+package can provide pieces of the configuration schema, which are stitched
+together to form a complete schema during validation. The configuration schema
+is also used to select what configuration is available in the frontend using a
+custom `visibility` keyword, as configuration is by default only available in
+the backend.
+
+You can validate your configuration against the schema using
+`backstage-cli config:check`, and define a schema for your own plugin either
+using JSON Schema or TypeScript. For more information, see
+[Defining Configuration](./defining.md).
+
 ## Reading Configuration
 
 As a plugin developer, you likely end up wanting to define configuration that
@@ -49,5 +63,5 @@ More details are provided in dedicated sections of the documentation.
   plugin.
 - [Writing Configuration](./writing.md): How to provide configuration for your
   Backstage deployment.
-- [Defining Configuration](./defining.md): How to define configuration for users
-  of your plugin.
+- [Defining Configuration](./defining.md): How to define a configuration schema
+  for users of your plugin or package.

docs/conf/writing.md

@@ -74,7 +74,7 @@ Note that if any config flags are provided, the default `app-config.yaml` files
 are NOT loaded. To include them you need to explicitly include them with a flag,
 for example:
 
-```
+```shell
 yarn start --config ../../app-config.yaml --config ../../app-config.staging.yaml
 ```
 
@@ -97,10 +97,10 @@ order:
 - If no config flags are provided, `app-config.local.yaml` has higher priority
   than `app-config.yaml`.
 
-## Secrets
+## Secrets and Dynamic Data
 
-Secrets are supported via a special secret keys that are prefixed with `$`,
-which in turn provides a number of different ways to read in secrets. To load a
+Secrets are supported via special data loading keys that are prefixed with `$`,
+which in turn provide a number of different ways to read in secrets. To load a
 configuration value as a secret, supply an object with one of the special secret
 keys, for example `$env` or `$file`. A full list of supported secret keys can be
 found below. For example, the following will read the config key
@@ -117,10 +117,6 @@ will return the value of the environment variable `MY_SECRET_KEY` when the
 backend started up. All secrets are loaded at startup, so changing the contents
 of secret files or environment variables will not be reflected at runtime.
 
-Note that secrets will never be included in the frontend bundle or development
-builds. When loading configuration you have to explicitly enable reading of
-secrets, which is only done for the backend configuration.
-
 As hinted at, secrets can be loaded from a bunch of different sources, and can
 be extended with more. Below is a list of the currently supported methods for
 loading secrets.
@@ -155,8 +151,11 @@ used to point to a specific value inside the file. Supported file extensions are
 
 ```yaml
 $data: ./my-secrets.json#deployment.key
+```
 
-# my-secrets.json
+Example `my-secrets.json` file:
+
+```json
 {
   "deployment": {
     "key": "my-secret-key"

docs/features/software-catalog/descriptor-format.md

@@ -2,8 +2,8 @@
 id: descriptor-format
 title: Descriptor Format of Catalog Entities
 sidebar_label: YAML File Format
-description: Documentation on Descriptor Format of Catalog Entities which
-describes the default data shape and semantics of catalog entities
+# prettier-ignore
+description: Documentation on Descriptor Format of Catalog Entities which describes the default data shape and semantics of catalog entities
 ---
 
 This section describes the default data shape and semantics of catalog entities.
@@ -22,11 +22,16 @@ we recommend that you name them `catalog-info.yaml`.
 - [Overall Shape Of An Entity](#overall-shape-of-an-entity)
 - [Common to All Kinds: The Envelope](#common-to-all-kinds-the-envelope)
 - [Common to All Kinds: The Metadata](#common-to-all-kinds-the-metadata)
+- [Common to All Kinds: Relations](#common-to-all-kinds-relations)
 - [Kind: Component](#kind-component)
 - [Kind: Template](#kind-template)
 - [Kind: API](#kind-api)
 - [Kind: Group](#kind-group)
 - [Kind: User](#kind-user)
+- [Kind: Resource](#kind-resource)
+- [Kind: System](#kind-system)
+- [Kind: Domain](#kind-domain)
+- [Kind: Location](#kind-location)
 
 ## Overall Shape Of An Entity
 
@@ -39,7 +44,7 @@ software catalog API.
   "kind": "Component",
   "metadata": {
     "annotations": {
-      "backstage.io/managed-by-location": "file:/tmp/component-info.yaml",
+      "backstage.io/managed-by-location": "file:/tmp/catalog-info.yaml",
       "example.com/service-discovery": "artistweb",
       "circleci.com/project-slug": "github/example-org/artist-website"
     },
@@ -89,6 +94,43 @@ significance and have reserved purposes and distinct shapes.
 
 See below for details about these fields.
 
+## Substitutions In The Descriptor Format
+
+The descriptor format supports substitutions using `$text`, `$json`, and
+`$yaml`.
+
+Placeholders like `$json: https://example.com/entity.json` are substituted by
+the content of the referenced file. Files can be referenced from any configured
+integration similar to locations by passing an absolute URL. It's also possible
+to reference relative files like `./referenced.yaml` from the same location.
+Relative references are handled relative to the folder of the
+`catalog-info.yaml` that contains the placeholder. There are three different
+types of placeholders:
+
+- `$text`: Interprets the contents of the referenced file as plain text and
+  embeds it as a string.
+- `$json`: Interprets the contents of the referenced file as JSON and embeds the
+  parsed structure.
+- `$yaml`: Interprets the contents of the referenced file as YAML and embeds the
+  parsed structure.
+
+For example, this can be used to load the definition of an API entity from a web
+server and embed it as a string in the field `spec.definition`:
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: petstore
+  description: The Petstore API
+spec:
+  type: openapi
+  lifecycle: production
+  owner: petstore@example.com
+  definition:
+    $text: https://petstore.swagger.io/v2/swagger.json
+```
+
 ## Common to All Kinds: The Envelope
 
 The root envelope object has the following structure.
@@ -259,6 +301,61 @@ This field is optional, and currently has no special semantics.
 Each tag must be sequences of `[a-z0-9]` separated by `-`, at most 63 characters
 in total.
 
+## Common to All Kinds: Relations
+
+The `relations` root field is a read-only list of relations, between the current
+entity and other entities, described in the
+[well-known relations section](well-known-relations.md). Relations are commonly
+two-way, so that there's a pair of relation types each describing one direction
+of the relation.
+
+A relation as part of a single entity that's read out of the API may look as
+follows.
+
+```js
+{
+  // ...
+  "relations": [
+    {
+      "target": {
+        "kind": "group",
+        "namespace": "default",
+        "name": "dev.infra"
+      },
+      "type": "ownedBy"
+    }
+  ],
+  "spec": {
+    "owner": "dev.infra",
+    // ...
+  }
+}
+```
+
+The fields of a relation are:
+
+| Field      | Type   | Description                                                                      |
+| ---------- | ------ | -------------------------------------------------------------------------------- |
+| `target`   | Object | A complete [compound reference](references.md) to the other end of the relation. |
+| `type`     | String | The type of relation FROM a source entity TO the target entity.                  |
+| `metadata` | Object | Reserved for future use.                                                         |
+
+Entity descriptor YAML files are not supposed to contain this field. Instead,
+catalog processors analyze the entity descriptor data and its surroundings, and
+deduce relations that are then attached onto the entity as read from the
+catalog.
+
+Where relations are produced, they are to be considered the authoritative source
+for that piece of data. In the example above, a plugin would do better to
+consume the relation rather than `spec.owner` for deducing the owner of the
+entity, because it may even be the case that the owner isn't taken from the YAML
+at all - it could be taken from a CODEOWNERS file nearby instead for example.
+Also, the `spec.owner` is on a shortened form and may have semantics associated
+with it (such as the default kind being `Group` if not specified).
+
+See the [well-known relations section](well-known-relations.md) for a list of
+well-known / common relations and their semantics.
+
 ## Kind: Component
 
 Describes the following entity kind:
@@ -285,7 +382,7 @@ spec:
   type: website
   lifecycle: production
   owner: artist-relations@example.com
-  implementsApis:
+  providesApis:
     - artist-api
 ```
 
@@ -310,7 +407,7 @@ The current set of well-known and common values for this field is:
 
 - `service` - a backend service, typically exposing an API
 - `website` - a website
-- `library` - a software library, such as an NPM module or a Java library
+- `library` - a software library, such as an npm module or a Java library
 
 ### `spec.lifecycle` [required]
 
@@ -349,12 +446,35 @@ group of people in an organizational structure.
 
 ### `spec.implementsApis` [optional]
 
+**NOTE**: This field was marked for deprecation on Nov 25nd, 2020. It will be
+removed entirely from the model on Dec 14th, 2020 in the repository and will not
+be present in released packages following the next release after that. Please
+update your code to not consume this field before the removal date.
+
 Links APIs that are implemented by the component, e.g. `artist-api`. This field
 is optional.
 
 The software catalog expects a list of one or more strings that references the
 names of other entities of the `kind` `API`.
 
+This field has the same behavior as `spec.providesApis`.
+
+### `spec.providesApis` [optional]
+
+Links APIs that are provided by the component, e.g. `artist-api`. This field is
+optional.
+
+The software catalog expects a list of one or more strings that references the
+names of other entities of the `kind` `API`.
+
+### `spec.consumesApis` [optional]
+
+Links APIs that are consumed by the component, e.g. `artist-api`. This field is
+optional.
+
+The software catalog expects a list of one or more strings that references the
+names of other entities of the `kind` `API`.
+
 ## Kind: Template
 
 Describes the following entity kind:
@@ -438,7 +558,7 @@ The current set of well-known and common values for this field is:
 
 - `service` - a backend service, typically exposing an API
 - `website` - a website
-- `library` - a software library, such as an NPM module or a Java library
+- `library` - a software library, such as an npm module or a Java library
 
 ### `spec.templater` [required]
 
@@ -533,6 +653,9 @@ The current set of well-known and common values for this field is:
   [OpenAPI](https://swagger.io/specification/) version 2 or version 3 spec.
 - `asyncapi` - An API definition based on the
   [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest/) spec.
+- `graphql` - An API definition based on
+  [GraphQL schemas](https://spec.graphql.org/) for consuming
+  [GraphQL](https://graphql.org/) based APIs.
 - `grpc` - An API definition based on
   [Protocol Buffers](https://developers.google.com/protocol-buffers) to use with
   [gRPC](https://grpc.io/).
@@ -600,10 +723,12 @@ metadata:
   description: The infra business unit
 spec:
   type: business-unit
+  profile:
+    displayName: Infrastructure
+    email: infrastructure@example.com
+    picture: https://example.com/groups/bu-infrastructure.jpeg
   parent: ops
-  ancestors: [ops, global-synergies, acme-corp]
   children: [backstage, other]
-  descendants: [backstage, other, team-a, team-b, team-c, team-d]
 ```
 
 In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
@@ -626,6 +751,14 @@ Some common values for this field could be:
 - `product-area`
 - `root` - as a common virtual root of the hierarchy, if desired
 
+### `spec.profile` [optional]
+
+Optional profile information about the group, mainly for display purposes. All
+fields of this structure are also optional. The email would be a group email of
+some form, that the group may wish to be used for contacting them. The picture
+is expected to be a URL pointing to an image that's representative of the group,
+and that a browser could fetch and render on a group page or similar.
+
 ### `spec.parent` [optional]
 
 The immediate parent group in the hierarchy, if any. Not all groups must have a
@@ -639,20 +772,6 @@ namespace as the user. Only `Group` entities may be referenced. Most commonly,
 this field points to a group in the same namespace, so in those cases it is
 sufficient to enter only the `metadata.name` field of that group.
 
-### `spec.ancestors` [required]
-
-The recursive list of parents up the hierarchy, by stepping through parents one
-by one. The list must be present, but may be empty if `parent` is not present.
-The first entry in the list is equal to `parent`, and then the following ones
-are progressively farther up the hierarchy.
-
-The entries of this array are
-[entity references](https://backstage.io/docs/features/software-catalog/references),
-with the default kind `Group` and the default namespace equal to the same
-namespace as the user. Only `Group` entities may be referenced. Most commonly,
-these entries point to groups in the same namespace, so in those cases it is
-sufficient to enter only the `metadata.name` field of those groups.
-
 ### `spec.children` [required]
 
 The immediate child groups of this group in the hierarchy (whose `parent` field
@@ -667,20 +786,6 @@ namespace as the user. Only `Group` entities may be referenced. Most commonly,
 these entries point to groups in the same namespace, so in those cases it is
 sufficient to enter only the `metadata.name` field of those groups.
 
-### `spec.descendants` [required]
-
-The immediate and recursive child groups of this group in the hierarchy
-(children, and children's children, etc.). The list must be present, but may be
-empty if there are no child groups. The items are not guaranteed to be ordered
-in any particular way.
-
-The entries of this array are
-[entity references](https://backstage.io/docs/features/software-catalog/references),
-with the default kind `Group` and the default namespace equal to the same
-namespace as the user. Only `Group` entities may be referenced. Most commonly,
-these entries point to groups in the same namespace, so in those cases it is
-sufficient to enter only the `metadata.name` field of those groups.
-
 ## Kind: User
 
 Describes the following entity kind:
@@ -740,3 +845,70 @@ with the default kind `Group` and the default namespace equal to the same
 namespace as the user. Only `Group` entities may be referenced. Most commonly,
 these entries point to groups in the same namespace, so in those cases it is
 sufficient to enter only the `metadata.name` field of those groups.
+
+## Kind: Resource
+
+This kind is not yet defined, but is reserved [for future use](system-model.md).
+
+## Kind: System
+
+This kind is not yet defined, but is reserved [for future use](system-model.md).
+
+## Kind: Domain
+
+This kind is not yet defined, but is reserved [for future use](system-model.md).
+
+## Kind: Location
+
+Describes the following entity kind:
+
+| Field        | Value                   |
+| ------------ | ----------------------- |
+| `apiVersion` | `backstage.io/v1alpha1` |
+| `kind`       | `Location`              |
+
+A location is a marker that references other places to look for catalog data.
+
+Descriptor files for this kind may look as follows.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Location
+metadata:
+  name: org-data
+spec:
+  type: url
+  targets:
+    - http://github.com/myorg/myproject/org-data-dump/catalog-info-staff.yaml
+    - http://github.com/myorg/myproject/org-data-dump/catalog-info-consultants.yaml
+```
+
+In addition to the [common envelope metadata](#common-to-all-kinds-the-metadata)
+shape, this kind has the following structure.
+
+### `apiVersion` and `kind` [required]
+
+Exactly equal to `backstage.io/v1alpha1` and `Location`, respectively.
+
+### `spec.type` [optional]
+
+The single location type, that's common to the targets specified in the spec. If
+it is left out, it is inherited from the location type that originally read the
+entity data. For example, if you have a `url` type location, that when read
+results in a `Location` kind entity with no `spec.type`, then the referenced
+targets in the entity will implicitly also be of `url` type. This is useful
+because you can define a hierarchy of things in a directory structure using
+relative target paths (see below), and it will work out no matter if it's
+consumed locally on disk from a `file` location, or as uploaded on a VCS.
+
+### `spec.target` [optional]
+
+A single target as a string. Can be either an absolute path/URL (depending on
+the type), or a relative path such as `./details/catalog-info.yaml` which is
+resolved relative to the location of this Location entity itself.
+
+### `spec.targets` [optional]
+
+A list of targets as strings. They can all be either absolute paths/URLs
+(depending on the type), or relative paths such as `./details/catalog-info.yaml`
+which are resolved relative to the location of this Location entity itself.

docs/features/software-catalog/extending-the-model.md

@@ -1,41 +1,351 @@
 ---
 id: extending-the-model
 title: Extending the model
-description: Documentation on Extending the model
+description: Documentation on extending the catalog model
 ---
 
-Backstage natively supports tracking of the following component
-[`type`](descriptor-format.md)'s:
+The Backstage catalog [entity data model](descriptor-format.md) is based on the
+[Kubernetes objects format](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/),
+and borrows a lot of its semantics as well. This page describes those semantics
+at a higher level and how to extend them to fit your organization.
 
-- Services
-- Websites
-- Libraries
-- Documentation
-- Other
+Backstage comes with a number of catalog concepts out of the box:
 
-![](../../assets/software-catalog/bsc-extend.png)
+- There are a number of builtin versioned _kinds_, such as `Component`, `User`
+  etc. These encapsulate the high level concept of an entity, and define the
+  schema for its entity definition data.
+- An entity has both a _metadata_ object and a _spec_ object at the root.
+- Each kind may or may not have a _type_. For example, there are several well
+  known types of component, such as `service` and `website`. These clarify the
+  more detailed nature of the entity, and may affect what features are exposed
+  in the interface.
+- Entities may have a number of _[annotations](well-known-annotations.md)_ on
+  them. These can be added either by humans into the descriptor files, or added
+  by automated processes when the entity is ingested into the catalog.
+- Entities may have a number of _labels_ on them.
+- Entities may have a number of _relations_, expressing how they relate to each
+  other in different ways.
 
-Since these types are likely not the only kind of software you will want to
-track in Backstage, it is possible to add your own software types that fit your
-organization's data model. Inside Spotify our model has grown significantly over
-the years, and now includes ML models, Apps, data pipelines and many more.
+We'll list different possibilities for extending this below.
 
-## Adding a new type
+## Adding a New apiVersion of an Existing Kind
 
-TODO: Describe what changes are needed to add a new type that shows up in the
-catalog.
+Example intents:
 
-## The Other type
+> "I want to evolve this core kind, tweaking the semantics a bit so I will bump
+> the apiVersion a step"
+
+> "This core kind is a decent fit but we want to evolve it at will so we'll move
+> it to our own company's apiVersion space and use that instead of
+> `backstage.io`."
+
+The `backstage.io` apiVersion space is reserved for use by the Backstage
+maintainers. Please do not change or add versions within that space.
+
+If you add an [apiVersion](descriptor-format.md#apiversion-and-kind-required)
+space of your own, you are effectively branching out from the underlying kind
+and making your own. An entity kind is identified by the apiVersion + kind pair,
+so even though the resulting entity may be similar to the core one, there will
+be no guarantees that plugins will be able to parse or understand its data. See
+below about adding a new kind.
+
+## Adding a New Kind
+
+Example intents:
+
+> "The kinds that come with the package are lacking. I want to model this other
+> thing that is a poor fit for either of the builtins."
+
+> "This core kind is a decent fit but we want to evolve it at will so we'll move
+> it to our own company's apiVersion space and use that instead of
+> `backstage.io`."
+
+A [kind](descriptor-format.md#apiversion-and-kind-required) is an overarching
+family, or an idea if you will, of entities that also share a schema. Backstage
+comes with a number of builtin ones that we believe are useful for a large
+variety of needs that one may want to model in Backstage. The primary ambition
+is to map things to these kinds, but sometimes you may want or need to extend
+beyond them.
+
+Introducing a new apiVersion is basically the same as adding a new kind. Bear in
+mind that most plugins will be compiled against the builtin
+`@backstage/catalog-model` package and have expectations that kinds align with
+that.
+
+The catalog backend itself, from a storage and API standpoint, does not care
+about the kind of entities it stores. Extending with new kinds is mainly a
+matter of permitting them to pass validation when building the backend catalog
+using the `CatalogBuilder`, and then to make plugins be able to understand the
+new kind.
+
+For the consuming side, it's a different story. Adding a kind has a very large
+impact. The very foundation of Backstage is to attach behavior and views and
+functionality to entities that we ascribe some meaning to. There will be many
+places where code checks `if (kind === 'X')` for some hard coded `X`, and casts
+it to a concrete type that it imported from a package such as
+`@backstage/catalog-model`.
+
+If you want to model something that doesn't feel like a fit for either of the
+builtin kinds, feel free to reach out to the Backstage maintainers to discuss
+how to best proceed.
+
+If you end up adding that new kind, you must namespace its `apiVersion`
+accordingly with a prefix that makes sense, typically based on your organization
+name - e.g. `my-company.net/v1`. Also do pick a new `kind` identifier that does
+not collide with the builtin kinds.
+
+## Adding a New Type of an Existing Kind
+
+Example intents:
+
+> "This is clearly a component, but it's of a type that doesn't quite fit with
+> the ones I've seen before."
+
+> "We don't call our teams "team", can't we put "flock" as the group type?"
+
+Some entity kinds have a `type` field in its spec. This is where an organization
+are free to express the variety of entities within a kind. This field is
+expected to follow some taxonomy that makes sense for yourself. The chosen value
+may affect what operations and views are enabled in Backstage for that entity.
+Inside Spotify our model has grown significantly over the years, and our
+component types now include ML models, apps, data pipelines and many more.
 
 It might be tempting to put software that doesn't fit into any of the existing
-types into Other. There are a few reasons why we advise against this; firstly,
-we have found that it is preferred to match the conceptual model that your
-engineers have when describing your software. Secondly, Backstage helps your
-engineers manage their software by integrating the infrastructure tooling
-through plugins. Different plugins are used for managing different types of
-components.
+types into an Other catch-all type. There are a few reasons why we advise
+against this; firstly, we have found that it is preferred to match the
+conceptual model that your engineers have when describing your software.
+Secondly, Backstage helps your engineers manage their software by integrating
+the infrastructure tooling through plugins. Different plugins are used for
+managing different types of components.
 
 For example, the
 [Lighthouse plugin](https://github.com/backstage/backstage/tree/master/plugins/lighthouse)
 only makes sense for Websites. The more specific you can be in how you model
 your software, the easier it is to provide plugins that are contextual.
+
+Adding a new type takes relatively little effort and carries little risk. Any
+type value is accepted by the catalog backend, but plugins may have to be
+updated if you want particular behaviors attached to that new type.
+
+## Changing the Validation Rules for The Entity Envelope or Metadata Fields
+
+Example intents:
+
+> "We want to import our old catalog but the default set of allowed characters
+> for a metadata.name are too strict."
+
+> "I want to change the rules for annotations so that I'm allowed to store any
+> data in annotation values, not just strings."
+
+After pieces of raw entity data have been read from a location, they are passed
+through a fixed number of so called `Validators`, as part of the entity policy
+check step. They ensure that the types and syntax of the base envelope and
+metadata make sense - in short, things that aren't entity-kind-specific. Some or
+all of these validators can be replaced when building the backend catalog using
+the `CatalogBuilder`.
+
+The risk and impact of this type of extension varies, based on what it is that
+you want to do. For example, extending the valid character set for kinds,
+namespaces and names can be fairly harmless, with a few notable exceptions -
+there is code that expects these to never ever contain a colon or slash, for
+example, and introducing URL-unsafe characters risks breaking plugins that
+aren't careful about encoding arguments. Supporting non-strings in annotations
+may be possible but has not yet been tried out in the real world - there is
+likely to be some level of plugin breakage that can be hard to predict.
+
+Before making this kind of extension, we recommend that you contact the
+Backstage maintainers or a support partner to discuss your use case.
+
+## Changing the Validation Rules for Core Entity Fields
+
+Example intent:
+
+> "I don't like that the owner is mandatory. I'd like it to be optional."
+
+After reading and policy-checked entity data from a location, it is sent through
+the processor chain looking for processors that implement the
+`validateEntityKind` step, to see that the data is of a known kind and abides by
+its schema. There is a builtin processor that implements this for all known core
+kinds and matches the data against their fixed validation schema. This processor
+can be replaced when building the backend catalog using the `CatalogBuilder`,
+with a processor of your own that validates the data differently.
+
+This type of extension is high risk, and may have high impact across the
+ecosystem depending on the type of change that is made. It is therefore not
+recommended in normal cases. There will be a large number of plugins and
+processors - and even the core itself - that make assumptions about the shape of
+the data and import the typescript data type from the `@backstage/catalog-model`
+package.
+
+## Adding New Fields to the Metadata Object
+
+Example intent:
+
+> "Our entities have this auxiliary property that I would like to express for
+> several entity kinds and it doesn't really fit as a spec field."
+
+The metadata object is currently left open for extension. Any unknown fields
+found in the metadata will just be stored verbatim in the catalog. However we
+want to caution against extending the metadata excessively. Firstly, you run the
+risk of colliding with future extensions to the model. Secondly, it is common
+that this type of extension lives more comfortably elsewhere - primarily in the
+metadata labels or annotations, but sometimes you even may want to make a new
+component type or similar instead.
+
+There are some situations where metadata can be the right place. If you feel
+that you have run into such a case and that it would apply to others, do feel
+free to contact the Backstage maintainers or a support partner to discuss your
+use case. Maybe we can extend the core model to benefit both you and others.
+
+## Adding New Fields to the Spec Object of an Existing Kind
+
+Example intent:
+
+> "The builtin Component kind is fine but we want to add an additional field to
+> the spec for describing whether it's in prod or staging."
+
+A kind's schema validation typically doesn't forbid "unknown" fields in an
+entity `spec`, and the catalog will happily store whatever is in it. So doing
+this will usually work from the catalog's point of view.
+
+Adding fields like this is subject to the same risks as mentioned about metadata
+extensions above. Firstly, you run the risk of colliding with future extensions
+to the model. Secondly, it is common that this type of extension lives more
+comfortably elsewhere - primarily in the metadata labels or annotations, but
+sometimes you even may want to make a new component type or similar instead.
+
+There are some situations where the spec can be the right place. If you feel
+that you have run into such a case and that it would apply to others, do feel
+free to contact the Backstage maintainers or a support partner to discuss your
+use case. Maybe we can extend the core model to benefit both you and others.
+
+## Adding a New Annotation
+
+Example intents:
+
+> "Our custom made build system has the concept of a named pipeline-set, and we
+> want to associate individual components with their corresponding pipeline-sets
+> so we can show their build status."
+
+> "We have an alerting system that automatically monitors service health, and
+> there's this integration key that binds the service to an alerts pool. We want
+> to be able to show the ongoing alerts for our services in Backstage so it'd be
+> nice to attach that integration key to the entity somehow."
+
+Annotations are mainly intended to be consumed by plugins, for feature detection
+or linking into external systems. Sometimes they are added by humans, but often
+they are automatically generated at ingestion time by processors. There is a set
+of [well-known annotations](well-known-annotations.md), but you are free to add
+additional ones. This carries no risk or impact to other systems as long as you
+abide by the following naming rules.
+
+- The `backstage.io` annotation prefix is reserved for use by the Backstage
+  maintainers. Reach out to us if you feel that you would like to make an
+  addition to that prefix.
+- Annotations that pertain to a well known third party system should ideally be
+  prefixed with a domain, in a way that makes sense to a reader and connects it
+  clearly to the system (or the maker of the system). For example, you might use
+  a `pagerduty.com` prefix for pagerduty related annotations, but maybe not
+  `ldap.com` for LDAP annotations since it's not directly affiliated with or
+  owned by an LDAP foundation/company/similar.
+- Annotations that have no prefix at all, are considered local to your Backstage
+  instance and can be used freely as such, but you should not make use of them
+  outside of your organization. For example, if you were to open source a plugin
+  that generates or consumes annotations, then those annotations must be
+  properly prefixed with your company domain or a domain that pertains to the
+  annotation at hand.
+
+## Adding a New Label
+
+Example intents:
+
+> "Our process reaping system wants to periodically scrape for components that
+> have a certain property."
+
+> "It'd be nice if our service owners could just tag their components somehow to
+> let the CD system know to automatically generate SRV records or not for that
+> service."
+
+Labels are mainly intended to be used for filtering of entities, by external
+systems that want to find entities that have some certain property. This is
+sometimes used for feature detection / selection. An example could be to add a
+label `deployments.my-company.net/register-srv: "true"`.
+
+At the time of writing this, the use of labels is very limited and we are still
+settling together with the community on how to best use them. If you feel that
+your use case fits the labels best, we would appreciate if you let the Backstage
+maintainers know.
+
+You are free to add labels. This carries no risk or impact to other systems as
+long as you abide by the following naming rules.
+
+- The `backstage.io` label prefix is reserved for use by the Backstage
+  maintainers. Reach out to us if you feel that you would like to make an
+  addition to that prefix.
+- Labels that pertain to a well known third party system should ideally be
+  prefixed with a domain, in a way that makes sense to a reader and connects it
+  clearly to the system (or the maker of the system). For example, you might use
+  a `pagerduty.com` prefix for pagerduty related labels, but maybe not
+  `ldap.com` for LDAP labels since it's not directly affiliated with or owned by
+  an LDAP foundation/company/similar.
+- Labels that have no prefix at all, are considered local to your Backstage
+  instance and can be used freely as such, but you should not make use of them
+  outside of your organization. For example, if you were to open source a plugin
+  that generates or consumes labels, then those labels must be properly prefixed
+  with your company domain or a domain that pertains to the label at hand.
+
+## Adding a New Relation Type
+
+Example intents:
+
+> "We have this concept of service maintainership, separate from ownership, that
+> we would like to make relations to individual users for."
+
+> We feel that we want to explicitly model the team-to-global-department mapping
+> as a relation, because it is core to our org setup and we frequently query for
+> it.
+
+Any processor can emit relations for entities as they are being processed, and
+new processors can be added when building the backend catalog using the
+`CatalogBuilder`. They can emit relations based on the entity data itself, or
+based on information gathered from elsewhere. Relations are directed and go from
+a source entity to a target entity. They are also tied to the entity that
+originated them - the one that was subject to processing when the relation was
+emitted. Relations may be dangling (referencing something that does not actually
+exist by that name in the catalog), and callers need to be aware of that.
+
+There is a set of [well-known relations](well-known-relations.md), but you are
+free to emit your own as well. You cannot change the fact that they are directed
+and have a source and target that have to be an
+[entity reference](references.md), but you can invent your own types. You do not
+have to make any changes to the catalog backend in order to accept new relation
+types.
+
+At the time of writing this, we do not have any namespacing/prefixing scheme for
+relation types. The type is also not validated to contain only some particular
+set of characters. Until rules for this are settled, you should stick to using
+only letters, dashes and digits, and to avoid collisions with future core
+relation types, you may want to prefix the type somehow. For example:
+`myCompany-maintainerOf` + `myCompany-maintainedBy`.
+
+If you have a suggestion for a relation type to be elevated to the core
+offering, reach out to the Backstage maintainers or a support partner.
+
+## Using a Well-Known Relation Type for a New Purpose
+
+Example intents:
+
+> "The ownerOf/ownedBy relation types sound like a good fit for expressing how
+> users are technical owners of our company specific ServiceAccount kind, and we
+> want to reuse those relation types for that."
+
+At the time of writing, this is uncharted territory. If the documented use of a
+relation states that one end of the relation commonly is a User or a Group, for
+example, then consumers are likely to have conditional statements on the form
+`if (x.kind === 'User') {} else {}`, which get confused when an unexpected kind
+appears.
+
+If you want to extend the use of an established relation type in a way that has
+an effect outside of your organization, reach out to the Backstage maintainers
+or a support partner to discuss risk/impact. It may even be that one end of the
+relation could be considered for addition to the core.

docs/features/software-catalog/external-integrations.md

@@ -1,8 +1,8 @@
 ---
 id: external-integrations
 title: External integrations
-description: Documentation on External integrations to integrate systems
-with Backstage
+# prettier-ignore
+description: Documentation on External integrations to integrate systems with Backstage
 ---
 
 Backstage natively supports importing catalog data through the use of

docs/features/software-catalog/index.md

@@ -2,8 +2,8 @@
 id: software-catalog-overview
 title: Backstage Service Catalog (alpha)
 sidebar_label: Overview
-description: The Backstage Service Catalog — actually, a software catalog, since
-it includes more than just services
+# prettier-ignore
+description: The Backstage Service Catalog — actually, a software catalog, since it includes more than just services
 ---
 
 ## What is a Service Catalog?

docs/features/software-catalog/references.md

@@ -51,7 +51,7 @@ spec:
   type: service
   lifecycle: experimental
   owner: group:pet-managers
-  implementsApis:
+  providesApis:
     - petstore
     - internal/streetlights
     - hello-world
@@ -66,7 +66,7 @@ catalog that is of kind `Group`, namespace `default` (which, actually, also can
 be left out in its own yaml file because that's the default value there too),
 and name `pet-managers`.
 
-The entries in `implementsApis` are also references. In this case, none of them
+The entries in `providesApis` are also references. In this case, none of them
 needs to specify a kind since we know from the context that that's the only kind
 that's supported here. The second entry specifies a namespace but the other ones
 don't, and in this context, the default is to refer to the same namespace as the

docs/features/software-catalog/well-known-annotations.md

@@ -2,9 +2,8 @@
 id: well-known-annotations
 title: Well-known Annotations on Catalog Entities
 sidebar_label: Well-known Annotations
-description: Documentation on lists a number of well known Annotations, that
-have defined semantics. They can be attached to catalog entities and consumed
-by plugins as needed
+# prettier-ignore
+description: Documentation that lists a number of well known Annotations, that have defined semantics. They can be attached to catalog entities and consumed by plugins as needed.
 ---
 
 This section lists a number of well known
@@ -191,9 +190,25 @@ metadata:
 ```
 
 The value of these annotations are the corresponding attributes that were found
-when ingestion the entity from LDAP. Not all of them may be present, depending
+when ingesting the entity from LDAP. Not all of them may be present, depending
 on what attributes that the server presented at ingestion time.
 
+### graph.microsoft.com/tenant-id, graph.microsoft.com/group-id, graph.microsoft.com/user-id
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    graph.microsoft.com/tenant-id: 6902611b-ffc1-463f-8af3-4d5285dc057b
+    graph.microsoft.com/group-id: c57e8ba2-6cc4-1039-9ebc-d5f241a7ca21
+    graph.microsoft.com/user-id: 2de244b5-104b-4e8f-a3b8-dce3c31e54b6
+```
+
+The value of these annotations are the corresponding attributes that were found
+when ingesting the entity from the Microsoft Graph API. Not all of them may be
+present, depending on what attributes that the server presented at ingestion
+time.
+
 ### sonarqube.org/project-key
 
 ```yaml
@@ -223,22 +238,9 @@ annotation, with the same value format.
 
 ### backstage.io/definition-at-location
 
-This annotation allowed to load the API definition from another location. Now
-placeholders can be used instead:
-
-```
-apiVersion: backstage.io/v1alpha1
-kind: API
-metadata:
-  name: petstore
-  description: The Petstore API
-spec:
-  type: openapi
-  lifecycle: production
-  owner: petstore@example.com
-  definition:
-    $text: https://petstore.swagger.io/v2/swagger.json
-```
+This annotation allowed to load the API definition from another location. Use
+[substitution](./descriptor-format.md#substitutions-in-the-descriptor-format)
+instead.
 
 ## Links
 

docs/features/software-catalog/well-known-relations.md

@@ -0,0 +1,93 @@
+---
+id: well-known-relations
+title: Well-known Relations between Catalog Entities
+sidebar_label: Well-known Relations
+# prettier-ignore
+description: Documentation that lists a number of well known Relations, that have defined semantics. They can be attached to catalog entities and consumed by plugins as needed.
+---
+
+This section lists a number of well known
+[entity relation types](descriptor-format.md#common-to-all-kinds-relations),
+that have defined semantics. They can be attached to catalog entities and
+consumed by plugins as needed.
+
+If you are looking to extend the set of relations, see
+[Extending the model](extending-the-model.md).
+
+## Relations
+
+This is a (non-exhaustive) list of relations that are known to be in active use.
+
+Each relation has a _source_ (implicitly: the entity that holds the relation), a
+_target_ (the entity to which the source has a relation), and a _type_ that
+tells what relation the source has with the target. The relation is directional;
+there are commonly pairs of relation types and the entity at the other end will
+have the opposite relation in the opposite direction (e.g. when querying for
+`A`, you will see `A.ownedBy.B`, and when querying `B`, you will see
+`B.ownerOf.A`).
+
+### `ownedBy` and `ownerOf`
+
+An ownership relation where the owner is usually an organizational entity
+([User](descriptor-format.md#kind-user) or
+[Group](descriptor-format.md#kind-group)), and the other entity can be anything.
+
+In Backstage, the owner of an entity is the singular entity (commonly a team)
+that bears ultimate responsibility for the entity, and has the authority and
+capability to develop and maintain it. They will be the point of contact if
+something goes wrong, or if features are to be requested. The main purpose of
+this relation is for display purposes in Backstage, so that people looking at
+catalog entities can get an understanding of to whom this entity belongs. It is
+not to be used by automated processes to for example assign authorization in
+runtime systems. There may be others that also develop or otherwise touch the
+entity, but there will always be one ultimate owner.
+
+This relation is commonly generated based on `spec.owner` of the owned entity,
+where present.
+
+### `providesApi` and `apiProvidedBy`
+
+A relation with an [API](descriptor-format.md#kind-api) entity, typically from a
+[Component](descriptor-format.md#kind-component) or
+[System](descriptor-format.md#kind-system).
+
+These relations express that a component or system exposes an API - meaning that
+it hosts callable endpoints from which you can consume that API.
+
+This relation is commonly generated based on `spec.providesApis` of the
+component or system in question.
+
+### `consumesApi` and `apiConsumedBy`
+
+A relation with an [API](descriptor-format.md#kind-api) entity, typically from a
+[Component](descriptor-format.md#kind-component) or
+[System](descriptor-format.md#kind-system).
+
+These relations express that a component or system consumes an API - meaning
+that it depends on endpoints of the API.
+
+This relation is commonly generated based on `spec.consumesApis` of the
+component or system in question.
+
+### `dependsOn` and `dependencyOf`
+
+A relation denoting a dependency on another entity.
+
+This relation is a general expression of being in need of that other entity for
+an entity to function. It can for example be used to express that a website
+component needs a library component as part of its build, or that a service
+component uses a persistent storage resource.
+
+### `parentOf` and `childOf`
+
+A parent/child relation to build up a tree, used for example to describe the
+organizational structure between [Groups](descriptor-format.md#kind-group).
+
+This relation is commonly based on `spec.parent` and/or `spec.children`.
+
+### `memberOf` and `hasMember`
+
+A membership relation, typically for [Users](descriptor-format.md#kind-user) in
+[Groups](descriptor-format.md#kind-group).
+
+This relation is commonly based on `spec.memberOf`.

docs/features/software-templates/adding-templates.md

@@ -55,6 +55,10 @@ contains more information about the required fields.
 Once we have a `template.yaml` ready, we can then add it to the service catalog
 for use by the scaffolder.
 
+_NOTE_: When the `publish` step is completed, it is currently assumed by the
+scaffolder that the final repository should contain a `catalog-info.yaml` in
+order to register this with the Catalog in Backstage.
+
 Currently the catalog supports loading definitions from GitHub + Local Files. To
 load from other places, not only will there need to be another preparer, but the
 support to load the location will also need to be added to the Catalog.

docs/features/techdocs/README.md

@@ -122,3 +122,12 @@ migrate Spotify's existing TechDocs features to open source.
   https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend
 [techdocs/container]: https://github.com/backstage/techdocs-container
 [techdocs/cli]: https://github.com/backstage/techdocs-cli
+
+## Feedback
+
+We have created a sweet and short TechDocs user survey -
+https://docs.google.com/forms/d/e/1FAIpQLSdn5Vn3MQhCdyYRuW8cMzZkMQF0bFxXYN168gZRvESLfJWVVg/viewform
+
+This is to gather inputs from you (the Backstage community) which will help us
+best serve TechDocs adopters and existing users. Your inputs will shape our
+roadmap and we will share it in the open.

docs/features/techdocs/architecture.md

@@ -1,7 +1,153 @@
 ---
 id: architecture
-title: Architecture
-description: Documentation on Architecture
+title: TechDocs Architecture
+description: Documentation on TechDocs Architecture
 ---
 
-![TechDocs Big Picture](../../assets/techdocs/techdocs_big_picture.png)
+## Basic (out-of-the-box)
+
+When you deploy Backstage (with TechDocs enabled by default), you get a basic
+out-of-the box experience.
+
+<img data-zoomable src="../../assets/techdocs/architecture-basic.drawio.svg" alt="TechDocs Architecture diagram" />
+
+> 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.
+
+<img data-zoomable src="../../assets/techdocs/architecture-recommended.drawio.svg" alt="TechDocs Architecture diagram" />
+
+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.
+
+**Work in progress 🚧**
+
+- Basic setup with cloud storage solution.
+
+**Not implemented yet ❌**
+
+- `techdocs-cli` is able to generate docs in CI/CD environment.
+- `techdocs-cli` is able to publish docs site to any storage.
+- `techdocs-backend` integration with Backstage access control management.

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',
+
+```

docs/features/techdocs/getting-started.md

@@ -95,7 +95,7 @@ environment is compatible with techdocs.
 You will have to install the `mkdocs` and `mkdocs-techdocs-core` package from
 pip, as well as `graphviz` and `plantuml` from your OS package manager (e.g.
 apt). See our
-[Dockerfile](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/Dockerfile)
+[Dockerfile](https://github.com/backstage/techdocs-container/blob/main/Dockerfile)
 for the latest requirements. You should be trying to match your Dockerfile with
 this one.
 
@@ -104,7 +104,7 @@ Note: We recommend Python version 3.7 or higher.
 Caveat: Please install the `mkdocs-techdocs-core` package after all other Python
 packages. The order is important to make sure we get correct version of some of
 the dependencies. For example, we want `Markdown` version to be
-[3.2.2](https://github.com/spotify/backstage/blob/f9f70c225548017b6a14daea75b00fbd399c11eb/packages/techdocs-container/techdocs-core/requirements.txt#L11).
+[3.2.2](https://github.com/backstage/backstage/blob/f9f70c225548017b6a14daea75b00fbd399c11eb/packages/techdocs-container/techdocs-core/requirements.txt#L11).
 You can also explicitly install `Markdown==3.2.2` after installing all other
 Python packages.
 

docs/features/techdocs/using-cloud-storage.md

@@ -0,0 +1,95 @@
+---
+id: using-cloud-storage
+title: Using Cloud Storage for TechDocs generated files
+description: Using Cloud Storage for TechDocs generated files
+---
+
+In the [TechDocs architecture](./architecture.md) you have the option to choose
+where you want to store the Generated static files which TechDocs uses to render
+documentation. In both the "Basic" and "Recommended" setup, you can add cloud
+storage providers like Google GCS, Amazon AWS S3, etc. By default, TechDocs uses
+the local filesystem of the `techdocs-backend` plugin in the "Basic" setup. And
+in the recommended setup, having one of the cloud storage is a prerequisite.
+Read more on the TechDocs Architecture documentation page.
+
+On this page you can read how to enable them.
+
+## Configuring Google GCS Bucket with TechDocs
+
+Follow the
+[official Google Cloud documentation](https://googleapis.dev/nodejs/storage/latest/index.html#quickstart)
+for the latest instructions on the following steps involving GCP.
+
+**1. Set `techdocs.publisher.type` config in your `app-config.yaml`**
+
+Set `techdocs.publisher.type` to `'googleGcs'`.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'googleGcs'
+```
+
+**2. GCP (Google Cloud Platform) Project**
+
+Create or choose a dedicated GCP project. Set
+`techdocs.publisher.googleGcs.projectId` to the project ID.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'googleGcs'
+  googleGcs:
+    projectId: 'gcp-project-id
+```
+
+**3. Service account API key**
+
+Create a new Service Account and a key associated with it. In roles of the
+service account, use "Storage Admin".
+
+If you want to create a custom role, make sure to include both `get` and
+`create` permissions for both "Objects" and "Buckets". See
+https://cloud.google.com/storage/docs/access-control/iam-permissions
+
+A service account can have many keys. Open your newly created account's page (in
+IAM & Admin console), and create a new key. Use JSON format for the key.
+
+A `<GCP-PROJECT-ID-random-uid>.json` file will be downloaded. This is the secret
+key TechDocs will use to make API calls. Make it available in your Backstage
+server and/or your local development server and set it in the app config
+`techdocs.publisher.googleGcs.credentials`.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'googleGcs'
+    googleGcs:
+      projectId: 'gcp-project-id'
+      credentials:
+        $file: '/path/to/google_application_credentials.json'
+```
+
+**4. GCS Bucket**
+
+Create a dedicated bucket for TechDocs sites. techdocs-backend will publish
+documentation to this bucket. TechDocs will fetch files from here to serve
+documentation in Backstage.
+
+Set the name of the bucket to `techdocs.publisher
+
+```yaml
+techdocs:
+  publisher:
+    type: 'googleGcs'
+    googleGcs:
+      projectId: 'gcp-project-id'
+      credentials:
+        $file: '/path/to/google_application_credentials.json'
+      bucketName: 'name-of-techdocs-storage-bucket'
+```
+
+**5. That's it!**
+
+Your Backstage app is now ready to use Google Cloud Storage for TechDocs, to
+store the static generated documentation files.

docs/getting-started/configure-app-with-plugins.md

@@ -6,7 +6,53 @@ description: Documentation on How Configuring App with plugins
 
 ## Adding existing plugins to your app
 
-Coming soon!
+The following steps assume that you have created a new Backstage app and want to
+add an existing plugin to it. We are using the
+[CircleCI](https://github.com/backstage/backstage/blob/master/plugins/circleci/README.md)
+plugin in this example.
+
+1. Add the plugin's npm package to the repo:
+
+```bash
+yarn add @backstage/plugin-circleci
+```
+
+2. Add the plugin itself:
+
+```js
+// packages/app/src/plugins.ts
+export { plugin as Circleci } from '@backstage/plugin-circleci';
+```
+
+3. Register the plugin router:
+
+```jsx
+// packages/app/src/components/catalog/EntityPage.tsx
+
+import { Router as CircleCIRouter } from '@backstage/plugin-circleci';
+
+// Then somewhere inside <EntityPageLayout>
+<EntityPageLayout.Content
+  path="/ci-cd/*"
+  title="CI/CD"
+  element={<CircleCIRouter />}
+/>;
+```
+
+Note that stand-alone plugins that are not "attached" to the Software Catalog
+would be added outside the `EntityPage`.
+
+4. [Optional] Add proxy config:
+
+```yaml
+// app-config.yaml
+proxy:
+  '/circleci/api':
+    target: https://circleci.com/api/v1.1
+    headers:
+      Circle-Token:
+        $env: CIRCLECI_AUTH_TOKEN
+```
 
 ### Adding a plugin page to the Sidebar
 

docs/getting-started/create-an-app.md

@@ -14,7 +14,7 @@ need to run Backstage in your own environment.
 
 To create a Backstage app, you will need to have
 [Node.js](https://nodejs.org/en/download/) Active LTS Release installed
-(currently v12).
+(currently v14).
 
 Backstage provides a utility for creating new apps. It guides you through the
 initial setup of selecting the name of the app and a database for the backend.
@@ -38,6 +38,42 @@ app-folder is the name that was provided when prompted.
 Inside that directory, it will generate all the files and folder structure
 needed for you to run your app.
 
+### Linking in local Backstage packages
+
+It can often be useful to try out changes to the packages in the main Backstage
+repo within your own app. For example if you want to make modifications to
+`@backstage/core` and try them out in your app.
+
+To link in external packages, add them to your `package.json` and `lerna.json`
+workspace paths. These can be either relative or absolute paths with or without
+globs. For example:
+
+```json
+"packages": [
+  "packages/*",
+  "plugins/*",
+  "../backstage/packages/core", // New path added to work on @backstage/core
+],
+```
+
+Then reinstall packages to make yarn set up symlinks:
+
+```bash
+yarn install
+```
+
+With this in place you can now modify the `@backstage/core` package within the
+main repo, and have those changes be reflected and tested in your app. Simply
+run your app using `yarn start` as normal.
+
+Note that for backend packages you need to make sure that linked packages are
+not dependencies of any non-linked package. If you for example want to work on
+`@backstage/backend-common`, you need to also link in other backend plugins and
+packages that depend on `@backstage/backend-common`, or temporarily disable
+those plugins in your backend. This is because the transformation of backend
+module tree stops whenever a non-local package is encountered, and from that
+point node will `require` packages directly for that entire module subtree.
+
 ### Troubleshooting
 
 The create app command doesn't always work as expected, this is a collection of
@@ -51,7 +87,7 @@ You may encounter the following error message:
 Couldn't find any versions for "file-saver" that matches "eligrey-FileSaver.js-1.3.8.tar.gz-art-external"
 ```
 
-This is likely because you have a globally configured NPM proxy, which breaks
+This is likely because you have a globally configured npm proxy, which breaks
 the installation of the `material-table` dependency. This is a known issue and
 being worked on in `material-table`, but for now you can work around it using
 the following:

docs/getting-started/index.md

@@ -10,7 +10,7 @@ you're planning to do.
 
 Creating a standalone instance makes it simpler to customize the application for
 your needs whilst staying up to date with the project. You will also depend on
-`@backstage` packages from NPM, making the project much smaller. This is the
+`@backstage` packages from npm, making the project much smaller. This is the
 recommended approach if you want to kick the tyres of Backstage or setup your
 own instance.
 

docs/getting-started/running-backstage-locally.md

@@ -8,19 +8,19 @@ description: Documentation on How to run Backstage Locally
 
 - Node.js
 
-First make sure you are using Node.js with an Active LTS Release, currently v12.
+First make sure you are using Node.js with an Active LTS Release, currently v14.
 This is made easy with a version manager such as
 [nvm](https://github.com/nvm-sh/nvm) which allows for version switching.
 
 ```bash
 # Installing a new version
-nvm install 12
-> Downloading and installing node v12.18.3...
-> Now using node v12.18.3 (npm v6.14.6)
+nvm install 14
+> Downloading and installing node v14.15.1...
+> Now using node v14.15.1 (npm v6.14.8)
 
 # Checking your version
 node --version
-> v12.18.3
+> v14.15.1
 ```
 
 - Yarn

docs/overview/roadmap.md

@@ -39,7 +39,7 @@ If you have questions about the roadmap or want to provide feedback, we would
 love to hear from you! Please create an
 [Issue](https://github.com/backstage/backstage/issues/new/choose), ping us on
 [Discord](https://discord.gg/EBHEGzX) or reach out directly at
-[alund@spotify.com](mailto:alund@spotify.com).
+[backstage-interest@spotify.com](mailto:backstage-interest@spotify.com).
 
 Want to help out? Awesome ❤️ Head over to
 [CONTRIBUTING](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md)

docs/overview/stability-index.md

@@ -0,0 +1,395 @@
+---
+id: stability-index
+title: Stability Index
+description:
+  An overview of the commitment to stability for different parts of the
+  Backstage codebase.
+---
+
+## Overview
+
+The purpose of the Backstage Stability Index is to communicate the stability of
+various parts of the project. It is tracked using a scoring system where a
+higher score indicates a higher level of stability and is a commitment to
+smoother transitions between breaking changes. Importantly, the Stability Index
+does not supersede [semver](https://semver.org/), meaning we will still adhere
+to semver and only do breaking changes in minor releases as long as we are on
+`0.x`.
+
+Each package or section is assigned a stability score between 0 and 3, with each
+point building on top of the previous one:
+
+- **0** - Breaking changes are noted in the changelog, and documentation is
+  updated.
+- **1** - The changelog entry includes a clearly documented upgrade path,
+  providing guidance for how to migrate previous usage patterns to the new
+  version.
+- **2** - Breaking changes always include a deprecation phase where both the old
+  and the new APIs can be used in parallel. This deprecation must have been
+  released for at least two weeks before the deprecated API is removed in a
+  minor version bump.
+- **3** - The time limit for the deprecation is 3 months instead of two weeks.
+
+TL;DR:
+
+- **0** - There's a changelog entry.
+- **1** - There's a migration guide.
+- **2** - 2 weeks of deprecation.
+- **3** - 3 months of deprecation.
+
+## Packages
+
+### `example-app` [GitHub](https://github.com/backstage/backstage/tree/master/packages/app/)
+
+This is the `packages/app` package, and it serves as an example as well as
+utility for local development in the main Backstage repo.
+
+Stability: `N/A`
+
+### `example-backend` [GitHub](https://github.com/backstage/backstage/tree/master/packages/backend/)
+
+This is the `packages/backend` package, and it serves as an example as well as
+utility for local development in the main Backstage repo.
+
+Stability: `N/A`
+
+### `backend-common` [GitHub](https://github.com/backstage/backstage/tree/master/packages/backend-common/)
+
+A collection of common helpers to be used by both backend plugins, and for
+constructing backend packages.
+
+Stability: `1`
+
+### `catalog-client` [GitHub](https://github.com/backstage/backstage/tree/master/packages/catalog-client/)
+
+An HTTP client for interacting with the catalog backend. Usable both in frontend
+and Backend.
+
+Stability: `0`. This is a very new addition and we have some immediate changes
+planned.
+
+### `catalog-model` [GitHub](https://github.com/backstage/backstage/tree/master/packages/catalog-model/)
+
+Contains the core catalog model, and utilities for working with entities. Usable
+both in frontend and Backend.
+
+Stability: `2`. The catalog model is evolving, but because of the broad usage we
+
+want to ensure some stability.
+
+### `cli` [GitHub](https://github.com/backstage/backstage/tree/master/packages/cli/)
+
+The main toolchain used for Backstage development. The various CLI commands and
+options passed to those commands, as well as the environment variables read by
+the CLI, are considered to be the interface that the stability index refers to.
+The build output may change over time and is not considered a breaking change
+unless it is likely to affect external tooling.
+
+Stability: `2`
+
+### `cli-common` [GitHub](https://github.com/backstage/backstage/tree/master/packages/cli-common/)
+
+Lightweight utilities used by the various Backstage CLIs, not intended for
+external use.
+
+Stability: `N/A`
+
+### `config` [GitHub](https://github.com/backstage/backstage/tree/master/packages/config/)
+
+Provides the logic and interfaces for reading static configuration.
+
+Stability: `2`
+
+### `config-loader` [GitHub](https://github.com/backstage/backstage/tree/master/packages/config-loader/)
+
+Used to load in static configuration, mainly for use by the CLI and
+@backstage/backend-common.
+
+Stability: `1`. Mainly intended for internal use.
+
+### `core` [GitHub](https://github.com/backstage/backstage/tree/master/packages/core/)
+
+#### Section: React Components
+
+All of the React components exported from `src/components/` and `src/layout/`
+
+Stability: `1`. These components have not received a proper review of the API,
+but we also want to ensure stability.
+
+#### Section: Plugin API
+
+The parts of the core API that are used by plugins, and the way plugins expose
+functionality to apps and other plugins. Includes for example `createPlugin`,
+`createRouteRef`, `createApiRef`.
+
+Stability: `2`. There are planned breaking changes around the way that plugins
+expose features and do routing. We still commit to keeping a short deprecation
+period so that plugins outside of the main repo have time to migrate.
+
+#### Section: App API
+
+The APIs used exclusively in the app, such as `createApp` and the system icons.
+
+Stability: `2`
+
+#### Section: Utility API Definitions
+
+The type declarations of the core Utility APIs.
+
+Stability: `2`. Changes to the Utility API type declarations need time to
+propagate.
+
+#### Section: Utility API Implementations
+
+The interfaces and default implementations for various Utility APIs, such as
+ErrorApi, IdentityApi, the auth APIs, etc.
+
+Stability: `1`. Most changes to the core utility APIs will not lead to
+widespread breaking changes since most apps rely on the default implementations.
+
+### `core-api` [GitHub](https://github.com/backstage/backstage/tree/master/packages/core-api/)
+
+The non-visual parts of @backstage/core. Everything in this packages is
+re-exported from @backstage/core, and this package should not be used directly.
+
+Stability: See @backstage/core
+
+### `create-app` [GitHub](https://github.com/backstage/backstage/tree/master/packages/create-app/)
+
+The CLI used to scaffold new Backstage projects.
+
+Stability: `2`
+
+### `dev-utils` [GitHub](https://github.com/backstage/backstage/tree/master/packages/dev-utils/)
+
+Provides utilities for developing plugins in isolation.
+
+Stability: `0`. This package is largely broken and needs updates.
+
+### `docgen` [GitHub](https://github.com/backstage/backstage/tree/master/packages/docgen/)
+
+Internal CLI utility for generating API Documentation.
+
+Stability: `N/A`
+
+### `e2e-test` [GitHub](https://github.com/backstage/backstage/tree/master/packages/e2e-test/)
+
+Internal CLI utility for running e2e tests.
+
+Stability: `N/A`
+
+### `integration` [GitHub](https://github.com/backstage/backstage/tree/master/packages/integration/)
+
+Provides shared utilities for managing integrations towards different types of
+third party systems. This package is currently internal and its functionality
+will likely be exposed via separate APIs in the future.
+
+Some of the functionality in this package is not available elsewhere yes, so if
+it's necessary it can be used, but there will be breaking changes.
+
+Stability: `0`
+
+### `storybook` [GitHub](https://github.com/backstage/backstage/tree/master/packages/storybook/)
+
+Internal storybook build for publishing stories to
+https://backstage.io/storybook
+
+Stability: `N/A`
+
+### `test-utils` [GitHub](https://github.com/backstage/backstage/tree/master/packages/test-utils/)
+
+Utilities for writing tests for Backstage plugins and apps.
+
+Stability: `2`
+
+### `test-utils-core` [GitHub](https://github.com/backstage/backstage/tree/master/packages/test-utils-core/)
+
+Internal testing utilities that are separated out for usage in
+@backstage/core-api. All exports are re-exported by @backstage/test-utils. This
+package should not be depended on directly.
+
+Stability: See @backstage/test-utils
+
+### `theme` [GitHub](https://github.com/backstage/backstage/tree/master/packages/theme/)
+
+The core Backstage MUI theme along with customization utilities.
+
+#### Section: TypeScript
+
+This is the TypeScript API exported by the theme package.
+
+Stability: `2`
+
+#### Section: Visual Theme
+
+The visual theme exported by the theme packages, where for example changing a
+color could be considered a breaking change.
+
+Stability: `1`
+
+## Plugins
+
+Plugins are rarely marked as stable as the `@backstage/core` plugin API is under
+heavy development.
+
+Many backend plugins are split into "REST API" and "TypeScript Interface"
+sections. The "TypeScript Interface" refers to the API used to integrate the
+plugin into the backend.
+
+Any plugin that is not listed below is untracked and can generally be considered
+unstable with a score of `0`. Open a Pull Request if you want your plugin to be
+added!
+
+### `api-docs` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/api-docs/)
+
+Components to discover and display API entities as an extension to the catalog
+plugin.
+
+Stability: `0`
+
+### `app-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/app-backend/)
+
+A backend plugin that can be used to serve the frontend app and inject
+configuration.
+
+Stability: `2`
+
+### `auth-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/auth-backend/)
+
+A backend plugin that implements the backend portion of the various
+authentication flows used in Backstage.
+
+#### Section: REST API
+
+Stability: `2`
+
+#### Section: TypeScript Interface
+
+Stability: `1`
+
+### `catalog` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/catalog/)
+
+The frontend plugin for the catalog, with the table and building blocks for the
+entity pages.
+
+Stability: `1`. We're planning some work to overhaul how entity pages are
+constructed.
+
+### `catalog-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend/)
+
+The backend API for the catalog, also exposes the processing subsystem for
+customization of the catalog. Powers the @backstage/plugin-catalog frontend
+plugin.
+
+#### Section: REST API
+
+Stability: `1`. There are plans to remove and rework some endpoints.
+
+#### Section: TypeScript Interface
+
+Stability: `1`. There are plans to rework parts of the Processor interface.
+
+### `catalog-graphql` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/catalog-graphql/)
+
+Provides the catalog schema and resolvers for the graphql backend.
+
+Stability: `0`. Under heavy development and subject to change.
+
+### `explore` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/explore/)
+
+A frontend plugin that introduces the concept of exploring internal and external
+tooling in an organization.
+
+Stability: `0`. Only an example at the moment and not customizable.
+
+### `graphiql` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/graphiql/)
+
+Integrates GraphiQL as a tool to browse GraphQL API endpoints inside Backstage.
+
+Stability: `1`
+
+### `graphql` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/graphql/)
+
+A backend plugin that provides
+
+Stability: `0`. Under heavy development and subject to change.
+
+### `kubernetes` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/kubernetes/)
+
+The frontend component of the Kubernetes plugin, used to browse and visualize
+Kubernetes resources.
+
+Stability: `1`.
+
+### `kubernetes-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/kubernetes-backend/)
+
+The backend component of the Kubernetes plugin, used to fetch Kubernetes
+resources from clusters and associate them with entities in the Catalog.
+
+Stability: `1`.
+
+### `proxy-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/proxy-backend/)
+
+A backend plugin used to set up proxying to other endpoints based on static
+configuration.
+
+Stability: `1`
+
+### `register-component` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/register-component/)
+
+A frontend plugin that allows the user to register entity locations in the
+catalog.
+
+Stability: `0`. This plugin is likely to be replaced by a generic entity import
+plugin instead.
+
+### `scaffolder` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/scaffolder/)
+
+The frontend scaffolder plugin where one can browse templates and initiate
+scaffolding jobs.
+
+Stability: `1`
+
+### `scaffolder-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend/)
+
+The backend scaffolder plugin that provides an implementation for templates in
+the catalog.
+
+Stability: `1`. There is planned work to rework the scaffolder in
+https://github.com/backstage/backstage/issues/2771.
+
+### `tech-radar` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/tech-radar/)
+
+Visualize the your company's official guidelines of different areas of software
+development.
+
+Stability: `0`
+
+### `techdocs` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/techdocs/)
+
+The frontend component of the TechDocs plugin, used to browse technical
+documentation of entities.
+
+Stability: `1`
+
+### `techdocs-backend` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend/)
+
+The backend component of the TechDocs plugin, used to transform and serve
+TechDocs.
+
+Stability: `0`
+
+### `user-settings` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/user-settings/)
+
+A frontend plugin that provides a page where the user can tweak various
+settings.
+
+Stability: `1`
+
+### `welcome` [GitHub](https://github.com/backstage/backstage/tree/master/plugins/welcome/)
+
+A plugin that can be used to welcome the user to Backstage.
+
+Stability: `0`. This used to be the start page for the example app, but has been
+replaced by the catalog plugin. It is still viewable at `/welcome` but may be
+removed.

docs/overview/vision.md

@@ -19,5 +19,5 @@ We are working on making Backstage the trusted standard toolbox (read: UX 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).
+vision, we'd love to talk. You can email us directly:
+[backstage-interest@spotify.com](mailto:backstage-interest@spotify.com).

docs/plugins/proxying.md

@@ -52,19 +52,7 @@ configuration will lead to the proxy acting on backend requests to
 
 The value inside each route is either a simple URL string, or an object on the
 format accepted by
-[http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware). It
-is also possible to limit the forwarded HTTP methods with the configuration
-`allowedMethods`, for example `allowedMethods: ['GET']` to enforce read-only
-access.
-
-By default, the proxy will only forward safe HTTP request headers to the target.
-Those are based on the headers that are considered safe for CORS and includes
-headers like `content-type` or `last-modified`, as well as all headers that are
-set by the proxy. If the proxy should forward other headers like
-`authorization`, this must be enabled by the `allowedHeaders` config, for
-example `allowedHeaders: ['Authorization']`. This should help to not
-accidentally forward confidential headers (`cookie`, `X-Auth-Request-User`) to
-third-parties.
+[http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware).
 
 If the value is a string, it is assumed to correspond to:
 
@@ -85,3 +73,22 @@ except with the following caveats for convenience:
   `'^/api/proxy/larger-example/v1/': '/'` is added. That means that a request to
   `/api/proxy/larger-example/v1/some/path` will be translated to a request to
   `http://larger.example.com:8080/svc.v1/some/path`.
+
+There are also additional settings:
+
+- `allowedMethods`: Limit the forwarded HTTP methods. For example
+  `allowedMethods: ['GET']` enforces read-only access.
+- `allowedHeaders`: A list of headers that should be forwarded to and received
+  from the target.
+
+By default, the proxy will only forward safe HTTP request headers to the target.
+Those are based on the headers that are considered safe for CORS and includes
+headers like `content-type` or `last-modified`, as well as all headers that are
+set by the proxy. If the proxy should forward other headers like
+`authorization`, this must be enabled by the `allowedHeaders` config, for
+example `allowedHeaders: ['Authorization']`. This should help to not
+accidentally forward confidential headers (`cookie`, `X-Auth-Request-User`) to
+third-parties.
+
+The same logic applies to headers that are sent from the target back to the
+frontend.

docs/plugins/publishing.md

@@ -1,16 +1,16 @@
 ---
 id: publishing
 title: Publishing
-description: Documentation on Publishing NPM packages
+description: Documentation on Publishing npm packages
 ---
 
-## NPM
+## npm
 
-NPM packages are published through CI/CD in the
+npm packages are published through CI/CD in the
 [.github/workflows/master.yml](https://github.com/backstage/backstage/blob/master/.github/workflows/master.yml)
 workflow. Every commit that is merged to master will be checked for new versions
 of all public packages, and any new versions will automatically be published to
-NPM.
+npm.
 
 ### Creating a new release
 

docs/plugins/testing.md

@@ -234,7 +234,7 @@ This is especially true for edge cases!
 
 ## Non-React Classes
 
-Testing a Javascript object which is _not_ a React component follows a lot of
+Testing a JavaScript object which is _not_ a React component follows a lot of
 the same principles as testing objects in other languages.
 
 ### API Testing Principles
@@ -243,7 +243,7 @@ Testing an API involves verifying four things:
 
 1. Invalid inputs are caught before being sent to the server.
 2. Valid inputs translate into a valid browser request.
-3. Server response is translated into an expected Javascript object.
+3. Server response is translated into an expected JavaScript object.
 4. Server errors are handled gracefully.
 
 ### Mocking API Calls