Merge pull request #10 from spotify/master

Merging master into fork

.changeset/config.json

@@ -34,7 +34,6 @@
       "@backstage/plugin-gitops-profiles",
       "@backstage/plugin-graphiql",
       "@backstage/plugin-graphql-backend",
-      "@backstage/plugin-identity-backend",
       "@backstage/plugin-jenkins",
       "@backstage/plugin-lighthouse",
       "@backstage/plugin-newrelic",

.changeset/create-app-url-reader-update.md

@@ -0,0 +1,6 @@
+---
+'example-backend': patch
+'@backstage/create-app': patch
+---
+
+Bump @backstage/catalog-backend and pass the now required UrlReader interface to the plugin

.changeset/metal-fishes-learn.md

@@ -0,0 +1,5 @@
+---
+'@backstage/create-app': minor
+---
+
+The default mount point for backend plugins have been changed to /api. These changes are done in the backend package itself, so it is recommended that you sync up existing backend packages with this new pattern.

.changeset/new-url-reader.md

@@ -0,0 +1,12 @@
+---
+'@backstage/backend-common': patch
+---
+
+Added new UrlReader interface for reading opaque data from URLs with different providers.
+
+This new URL reading system is intended as a replacement for the various integrations towards
+external systems in the catalog, scaffolder, and techdocs. It is configured via a new top-level
+config section called 'integrations'.
+
+Along with the UrlReader interface is a new UrlReaders class, which exposes static factory
+methods for instantiating readers that can read from many different integrations simultaneously.

.changeset/url-reader-processor.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': minor
+---
+
+The catalog backend UrlReaderProcessor now uses a UrlReader from @backstage/backend-common, which must now be supplied to the constructor.

.codecov.yml

@@ -13,6 +13,8 @@ flags:
   core:
     paths:
       - packages/core/
+    carryforward: true
   core-api:
     paths:
       - packages/core-api/
+    carryforward: true

.github/CODEOWNERS

@@ -6,6 +6,8 @@
 
 *                                           @spotify/backstage-core
 /docs/features/techdocs                     @spotify/techdocs-core
+/plugins/cost-insights                      @spotify/silver-lining
+/plugins/cloudbuild                         @trivago/ebarrios
 /plugins/techdocs                           @spotify/techdocs-core
 /plugins/techdocs-backend                   @spotify/techdocs-core
 /packages/techdocs-cli                      @spotify/techdocs-core

.github/styles/vocab.txt

@@ -0,0 +1,203 @@
+abc
+Apdex
+api
+Api
+apis
+args
+asciidoc
+async
+Avro
+backrub
+Balachandran
+Bigtable
+Blackbox
+bool
+boolean
+Chai
+changeset
+changesets
+Changesets
+changset
+chanwit
+Chanwit
+cisphobia
+cissexist
+classname
+cli
+cncf
+codeblocks
+Codecov
+codehilite
+Codehilite
+codeowners
+config
+Config
+configs
+const
+cookiecutter
+css
+dariddler
+deadnaming
+destructured
+dev
+devs
+discoverability
+Discoverability
+dls
+docgen
+Dockerfile
+Dockerize
+dockerode
+Docusaurus
+eg
+Ek
+env
+Env
+eslint
+facto
+failover
+Figma
+Firekube
+Fredrik
+github
+Github
+Gitlab
+graphql
+graphviz
+Hackathons
+haproxy
+heroku
+Hostname
+http
+https
+img
+incentivised
+inlinehilite
+interop
+javascript
+Javascript
+jq
+js
+json
+jsx
+Kaewkasi
+Knex
+kubectl
+kubernetes
+learnings
+lerna
+Lerna
+magiclink
+mailto
+Malus
+md
+microsite
+middleware
+minikube
+Minikube
+misgendering
+mkdocs
+Mkdocs
+monorepo
+Monorepo
+monorepos
+msw
+namespace
+Namespaces
+neuro
+newrelic
+nginx
+Niklas
+nohoist
+nonces
+npm
+nvm
+oauth
+Oauth
+Okta
+Oldsberg
+onboarding
+Onboarding
+pagerduty
+Patrik
+Phoen
+plantuml
+Pomaceous
+postgres
+pre
+prebaked
+preconfigured
+Preprarer
+Prerequisities
+productional
+Protobuf
+proxying
+Proxying
+pygments
+pymdownx
+Raghunandan
+rankdir
+readme
+Readme
+Redash
+repo
+Repo
+repos
+rerender
+rollbar
+Rollbar
+Rollup
+Rosaceae
+rst
+rsync
+ruleset
+sam
+scaffolded
+scaffolder
+Scaffolder
+semlas
+Serverless
+Sinon
+smartsymobls
+sparklines
+Spotifiers
+spotify
+Spotify
+squidfunk
+src
+subkey
+superfences
+Superfences
+talkdesk
+Talkdesk
+tasklist
+techdocs
+templated
+templater
+Templater
+templaters
+Templaters
+Thauer
+theres
+toc
+tolerations
+Tolerations
+toolsets
+touchpoints
+ui
+upvote
+url
+utils
+validators
+Voi
+Wealthsimple
+Weaveworks
+xyz
+yaml
+Zalando
+Zhou
+Billett
+cloudbuild
+Grafana
+Iain
+Snyk

.github/workflows/chromatic-storybook-test.yml

@@ -26,7 +26,7 @@ jobs:
         uses: actions/cache@v2
         with:
           path: '**/node_modules'
-          key: ${{ runner.os }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+          key: ${{ runner.os }}-v${{ matrix.node-version }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
       - name: find location of global yarn cache
         id: yarn-cache
         if: steps.cache-modules.outputs.cache-hit != 'true'

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x]
+        node-version: [12.x, 14.x]
 
     env:
       CI: true
@@ -37,7 +37,7 @@ jobs:
           path: '**/node_modules'
           # We use both yarn.lock and package.json as cache keys to ensure that
           # changes to local monorepo packages bust the cache.
-          key: ${{ runner.os }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+          key: ${{ runner.os }}-v${{ matrix.node-version }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
 
       # If we get a cache hit for node_modules, there's no need to bring in the global
       # yarn cache or run yarn install, as all dependencies will be installed already.

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,71 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+name: 'CodeQL'
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [master]
+  schedule:
+    - cron: '0 8 * * 6'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # Override automatic language detection by changing the below list
+        # Supported options are ['csharp', 'cpp', 'go', 'java', 'javascript', 'python']
+        language: ['javascript']
+        # Learn more...
+        # https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#overriding-automatic-language-detection
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          # We must fetch at least the immediate parents so that if this is
+          # a pull request then we can checkout the head.
+          fetch-depth: 2
+
+      # If this run was triggered by a pull request event, then checkout
+      # the head of the pull request instead of the merge commit.
+      - run: git checkout HEAD^2
+        if: ${{ github.event_name == 'pull_request' }}
+
+      # Initializes the CodeQL tools for scanning.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v1
+        with:
+          languages: ${{ matrix.language }}
+          # If you wish to specify custom queries, you can do so here or in a config file.
+          # By default, queries listed here will override any specified in a config file.
+          # Prefix the list here with "+" to use these queries and those in the config file.
+          # queries: ./path/to/local/query, your-org/your-repo/queries@main
+
+      # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+      # If this step fails, then you should remove it and run the build manually (see below)
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v1
+
+      # ℹ️ Command-line programs to run using the OS shell.
+      # 📚 https://git.io/JvXDl
+
+      # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+      #    and modify them (or add more) to build your code if your project
+      #    uses a compiled language
+
+      #- run: |
+      #   make bootstrap
+      #   make release
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v1

.github/workflows/docs-quality-checker.yml

@@ -0,0 +1,18 @@
+name: Check Markdown files quality
+
+on:
+  pull_request:
+    branches: [master]
+    paths:
+      - '**.md'
+
+jobs:
+  check-all-files:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: documentation quality check
+        uses: errata-ai/vale-action@v1.3.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/e2e-win.yml

@@ -17,7 +17,7 @@ jobs:
     strategy:
       matrix:
         os: [windows-latest]
-        node-version: [12.x]
+        node-version: [12.x, 14.x]
 
     env:
       CI: true
@@ -31,6 +31,8 @@ jobs:
         uses: actions/setup-node@v1
         with:
           node-version: ${{ matrix.node-version }}
+      - name: Add msbuild to PATH
+        uses: microsoft/setup-msbuild@v1.0.1
       - name: yarn install
         run: yarn install --frozen-lockfile
 

.github/workflows/e2e.yml

@@ -26,7 +26,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        node-version: [12.x]
+        node-version: [12.x, 14.x]
 
     env:
       CI: true
@@ -47,7 +47,7 @@ jobs:
         uses: actions/cache@v2
         with:
           path: '**/node_modules'
-          key: ${{ runner.os }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+          key: ${{ runner.os }}-v${{ matrix.node-version }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
       - name: find location of global yarn cache
         id: yarn-cache
         if: steps.cache-modules.outputs.cache-hit != 'true'

.github/workflows/master-win.yml

@@ -10,7 +10,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x]
+        node-version: [12.x, 14.x]
 
     env:
       CI: true

.github/workflows/master.yml

@@ -10,7 +10,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x]
+        node-version: [12.x, 14.x]
 
     env:
       CI: true
@@ -30,7 +30,7 @@ jobs:
         uses: actions/cache@v2
         with:
           path: '**/node_modules'
-          key: ${{ runner.os }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+          key: ${{ runner.os }}-v${{ matrix.node-version }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
       - name: find location of global yarn cache
         id: yarn-cache
         if: steps.cache-modules.outputs.cache-hit != 'true'
@@ -69,12 +69,14 @@ jobs:
 
       # Publishes current version of packages that are not already present in the registry
       - name: publish
+        if: matrix.node-version == '12.x'
         run: yarn lerna -- publish from-package --yes
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       # Tags the commit with the version in the core package if the tag doesn't exist
       - uses: Klemensas/action-autotag@1.2.3
+        if: matrix.node-version == '12.x'
         with:
           GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
           package_root: 'packages/core'

.github/workflows/microsite-build-check.yml

@@ -13,7 +13,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x]
+        node-version: [12.x, 14.x]
 
     env:
       CI: true
@@ -33,6 +33,10 @@ jobs:
         run: yarn install --frozen-lockfile
         working-directory: microsite
 
+      - name: prettier
+        run: yarn prettier:check
+        working-directory: microsite
+
       - name: build microsite
         run: yarn build
         working-directory: microsite

.github/workflows/nightly.yml

@@ -0,0 +1,77 @@
+name: Nightly Snapshot Release
+
+on:
+  schedule:
+    - cron: '0 2 * * *' # run at 2 AM UTC
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [14.x]
+
+    env:
+      CI: true
+      NODE_OPTIONS: --max-old-space-size=4096
+
+    steps:
+      - uses: actions/checkout@v2
+
+      # Beginning of yarn setup, keep in sync between all workflows, see ci.yml
+      - name: use node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: https://registry.npmjs.org/ # Needed for auth
+      - name: cache all node_modules
+        id: cache-modules
+        uses: actions/cache@v2
+        with:
+          path: '**/node_modules'
+          key: ${{ runner.os }}-v${{ matrix.node-version }}-node_modules-${{ hashFiles('yarn.lock', '**/package.json') }}
+      - name: find location of global yarn cache
+        id: yarn-cache
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+      - name: cache global yarn cache
+        uses: actions/cache@v2
+        if: steps.cache-modules.outputs.cache-hit != 'true'
+        with:
+          path: ${{ steps.yarn-cache.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+      - name: yarn install
+        run: yarn install --frozen-lockfile
+      # End of yarn setup
+
+      # No verification done here, only build & publish. If the master branch
+      # is broken we will see that from those builds, but we still want to push nightly
+      # builds since upgrading to them is a manual process anyway.
+
+      - name: tsc
+        run: yarn tsc
+      - name: build
+        run: yarn build
+
+      # Prepares a nightly release version of any package with pending changesets
+      - 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
+      # 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
+        run: yarn changeset publish --tag nightly
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Discord notification
+        if: ${{ failure() }}
+        uses: Ilshidur/action-discord@0.2.0
+        env:
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+        with:
+          args: 'Nightly build failed https://github.com/{{GITHUB_REPOSITORY}}/actions/runs/{{GITHUB_RUN_ID}}'

.github/workflows/scaffolder.yml

@@ -1,33 +0,0 @@
-name: Scaffolder
-
-on:
-  pull_request:
-    paths:
-      - '.github/workflows/scaffolder.yml'
-      - './plugins/scaffolder-backend/scripts'
-  push:
-    branches: [master]
-jobs:
-  build:
-    runs-on: ${{ matrix.os }}
-
-    strategy:
-      matrix:
-        os: [ubuntu-latest]
-        python-version: [3.7]
-
-    name: Build Container
-    steps:
-      - uses: actions/checkout@v2
-      # Build Docker Image
-      - name: Build and push Docker images
-        uses: docker/build-push-action@v1.1.0
-        with:
-          path: plugins/scaffolder-backend/scripts
-          dockerfile: plugins/scaffolder-backend/scripts/Cookiecutter.dockerfile
-          registry: docker.pkg.github.com
-          repository: ${{ github.repository }}/cookiecutter
-          username: ${{ github.actor }}
-          password: ${{ github.token }}
-          tag_with_ref: true
-          push: true

.prettierignore

@@ -1,6 +1,6 @@
 .yarn
 dist
-microsite/build
+microsite
 coverage
 *.hbs
 templates

.vale.ini

@@ -0,0 +1,4 @@
+StylesPath = .github/styles
+
+[*.md]
+BasedOnStyles = Vale

CHANGELOG.md

@@ -8,6 +8,30 @@ If you encounter issues while upgrading to a newer version, don't hesitate to re
 
 > Collect changes for the next release below
 
+### Backend (example-backend, or backends created with @backstage/create-app)
+
+- The default mount point for backend plugins have been changed to `/api`. These changes are done in the backend package itself, so it is recommended that you sync up existing backend packages with this new pattern. [#2562](https://github.com/spotify/backstage/pull/2562)
+- A service discovery mechanism for backend plugins has been added, and is now a requirement for several backend plugins. See [packages/backend/src/index.ts](./packages/backend/src/index.ts) for how to set it up using `SingleHostDiscovery` from `@backstage/backend-common`. Note that the default base path for plugins is set to `/api` to that change, but it can be set to use the old behavior via the `basePath` option. [#2600](https://github.com/spotify/backstage/pull/2600)
+
+### @backstage/auth-backend
+
+- The default mount path of backend plugins was changed to `/api/:pluginId`, and as part of that it was needed to enable configuration of the base path of the auth backend, so that it can construct redirect URLs correctly. Note that you will also need to reconfigure any allowed redirect URLs to include `/api` if you switch to the new recommended pattern. [#2562](https://github.com/spotify/backstage/pull/2562)
+- The auth backend now requires an implementation of `PluginEndpointDiscovery` from `@backstage/backend-common` to be passed in as `discovery`. See the changes to `@backstage/backend`.
+
+### @backstage/proxy-backend
+
+- The proxy backend now requires an implementation of `PluginEndpointDiscovery` from `@backstage/backend-common` to be passed in as `discovery`. See the changes to `@backstage/backend`.
+
+### @backstage/techdocs-backend
+
+- The TechDocs backend now requires an implementation of `PluginEndpointDiscovery` from `@backstage/backend-common` to be passed in as `discovery`. See the changes to `@backstage/backend`.
+
+### @backstage/plugin-identity-backend
+
+- This plugin was removed, remove it from your backend if it's there. [#2616](https://github.com/spotify/backstage/pull/2616)
+
+## v0.1.1-alpha.23
+
 ### @backstage/core
 
 - Renamed `SessionStateApi` to `SessionApi` and `logout` to `signOut`. Custom implementations of the `SingInPage` app-component will need to rename their `logout` function. The different auth provider items for the `UserSettingsMenu` have been consolidated into a single `ProviderSettingsItem`, meaning you need to replace existing usages of `OAuthProviderSettings` and `OIDCProviderSettings`. [#2555](https://github.com/spotify/backstage/pull/2555).

CONTRIBUTING.md

@@ -28,10 +28,14 @@ What kind of plugins should/could be created? Some inspiration from the 120+ plu
 
 ## Suggesting a plugin
 
-If you start developing a plugin that you aim to release as open source, we suggest that you create a new [new Issue](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). This helps the community know what plugins are in development.
+If you start developing a plugin that you aim to release as open source, we suggest that you create a [new Issue](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). This helps the community know what plugins are in development.
 
 You can also use this process if you have an idea for a good plugin but you hope that someone else will pick up the work.
 
+## Adding Non-code Contributions
+
+Since there is such a large landscape of possible development, build, and deployment environments, we welcome community contributions in these areas in the [`/contrib`](https://github.com/spotify/backstage/tree/master/contrib) folder of the project. This is an excellent place to put things that help out the community at large, but which may not fit within the scope of the core product to support natively. Here, you will find Helm charts, alternative Docker images, and much more.
+
 ## Write Documentation
 
 The current documentation is very limited. Help us make the `/docs` folder come alive.
@@ -72,6 +76,8 @@ If you're contributing to the backend or CLI tooling, be mindful of cross-platfo
 
 Also be sure to skim through our [ADRs](https://github.com/spotify/backstage/tree/master/docs/architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](https://github.com/spotify/backstage/blob/master/docs/architecture-decisions/adr006-avoid-react-fc.md) is one to look out for.
 
+If there are any updates in `markdown` file please make sure to run `yarn run lint:docs`. Though it is checked on `lint-staged`. It is required to install [vale](https://docs.errata.ai/vale/install) separately and make sure it is accessed by global command.
+
 # Creating Changesets
 
 We use [changesets](https://github.com/atlassian/changesets) to help us prepare releases. It helps us make sure that every package affected by a change gets a proper version number and an entry in its `CHANGELOG.md`. To make the process of generating releases easy. it helps when contributors include changesets with their pull requests.

DEPLOYMENT.md

@@ -4,7 +4,7 @@
 
 Deploying to heroku is relatively easy following these steps.
 
-First, make sure you have the [heroku CLI installed](https://devcenter.heroku.com/articles/heroku-cli) and log into it as well as loging into Heroku's [container registry](https://devcenter.heroku.com/articles/container-registry-and-runtime).
+First, make sure you have the [heroku CLI installed](https://devcenter.heroku.com/articles/heroku-cli) and log into it as well as login into Heroku's [container registry](https://devcenter.heroku.com/articles/container-registry-and-runtime).
 
 ```bash
 $ heroku login

README.md

@@ -26,6 +26,8 @@ Out of the box, Backstage includes:
 
 For more information go to [backstage.io](https://backstage.io) or join our [Discord chatroom](https://discord.gg/EBHEGzX).
 
+🎉 Backstage is a CNCF Sandbox project. Read the announcement [here](https://backstage.io/blog/2020/09/23/backstage-cncf-sandbox).
+
 ## Project roadmap
 
 A detailed project roadmap, including already delivered milestones, is available [here](https://backstage.io/docs/overview/roadmap).
@@ -51,11 +53,9 @@ Check out [the documentation](https://backstage.io/docs/getting-started) on how
 - [Code of Conduct](CODE_OF_CONDUCT.md) - This is how we roll
 - [Adopters](ADOPTERS.md) - Companies already using Backstage
 - [Blog](https://backstage.io/blog/) - Announcements and updates
-- [Newsletter](https://mailchi.mp/spotify/backstage-community)
+- [Newsletter](https://mailchi.mp/spotify/backstage-community) - Subscribe to our email newsletter
 - Give us a star ⭐️ - If you are using Backstage or think it is an interesting project, we would love a star ❤️
 
-Or, if you are an open source developer and are interested in joining our team, please reach out to [foss-opportunities@spotify.com ](mailto:foss-opportunities@spotify.com)
-
 ## License
 
 Copyright 2020 Spotify AB.

app-config.development.yaml

@@ -9,3 +9,5 @@ backend:
     origin: http://localhost:3000
     methods: [GET, POST, PUT, DELETE]
     credentials: true
+  csp:
+    connect-src: ["'self'", 'http:', 'https:']

app-config.yaml

@@ -9,14 +9,13 @@ backend:
   database:
     client: sqlite3
     connection: ':memory:'
+  csp:
+    connect-src: ["'self'", 'https:']
 
 # See README.md in the proxy-backend plugin for information on the configuration format
 proxy:
   '/circleci/api':
     target: https://circleci.com/api/v1.1
-    changeOrigin: true
-    pathRewrite:
-      '^/proxy/circleci/api/': '/'
     headers:
       Circle-Token:
         $secret:
@@ -29,12 +28,21 @@ proxy:
         $secret:
           env: JENKINS_BASIC_AUTH_HEADER
 
+  '/travisci/api':
+    target: https://api.travis-ci.com
+    changeOrigin: true
+    headers:
+      Authorization:
+        $secret:
+          env: TRAVISCI_AUTH_TOKEN
+      travis-api-version: 3
+
 organization:
   name: Spotify
 
 techdocs:
-  storageUrl: http://localhost:7000/techdocs/static/docs
-  requestUrl: http://localhost:7000/techdocs/docs
+  storageUrl: http://localhost:7000/api/techdocs/static/docs
+  requestUrl: http://localhost:7000/api/techdocs
   generators:
     techdocs: 'docker'
 
@@ -55,11 +63,53 @@ newrelic:
 lighthouse:
   baseUrl: http://localhost:3003
 
+kubernetes:
+  clusterLocatorMethod: 'configMultiTenant'
+  clusters: []
+
+integrations:
+  github:
+    - host: github.com
+      token:
+        $secret:
+          env: GITHUB_PRIVATE_TOKEN
+    ### Example for how to add your GitHub Enterprise instance using the API:
+    # - host: ghe.example.net
+    #   apiBaseUrl: https://ghe.example.net/api/v3
+    #   token:
+    #     $secret:
+    #       env: GHE_PRIVATE_TOKEN
+    ### Example for how to add your GitHub Enterprise instance using raw HTTP fetches (token is optional):
+    # - host: ghe.example.net
+    #   rawBaseUrl: https://ghe.example.net/raw
+    #   token:
+    #     $secret:
+    #       env: GHE_PRIVATE_TOKEN
+  gitlab:
+    - host: gitlab.com
+      token:
+        $secret:
+          env: GITLAB_PRIVATE_TOKEN
+  bitbucket:
+    - host: bitbucket.org
+      username:
+        $secret:
+          env: BITBUCKET_USERNAME
+      appPassword:
+        $secret:
+          env: BITBUCKET_APP_PASSWORD
+  azure:
+    - host: dev.azure.com
+      token:
+        $secret:
+          env: AZURE_PRIVATE_TOKEN
+
 catalog:
   rules:
-    - allow: [Component, API, Group, Template, Location]
+    - allow: [Component, API, Group, User, Template, Location]
+
   processors:
-    github:
+    githubOrg:
       providers:
         - target: https://github.com
           token:
@@ -71,47 +121,22 @@ catalog:
         #   token:
         #     $secret:
         #       env: GHE_PRIVATE_TOKEN
-        #### Example for how to add your GitHub Enterprise instance using raw HTTP fetches (token is optional):
-        # - target: https://ghe.example.net
-        #   rawBaseUrl: https://ghe.example.net/raw
-        #   token:
-        #     $secret:
-        #       env: GHE_PRIVATE_TOKEN
-    bitbucketApi:
-      username:
-        $secret:
-          env: BITBUCKET_USERNAME
-      appPassword:
-        $secret:
-          env: BITBUCKET_APP_PASSWORD
-    gitlabApi:
-      privateToken:
-        $secret:
-          env: GITLAB_PRIVATE_TOKEN
-    azureApi:
-      privateToken:
-        $secret:
-          env: AZURE_PRIVATE_TOKEN
 
   locations:
     # Backstage example components
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/all-components.yaml
-
     # Example component for github-actions
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/plugins/github-actions/examples/sample.yaml
-
     # Example component for techdocs
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/plugins/techdocs-backend/examples/documented-component/documented-component.yaml
-
     # Backstage example APIs
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/all-apis.yaml
-
     # Backstage example templates
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/all-templates.yaml
 
 scaffolder:
@@ -126,6 +151,12 @@ scaffolder:
       token:
         $secret:
           env: GITLAB_ACCESS_TOKEN
+  azure:
+    baseUrl: https://dev.azure.com/{your-organization}
+    api:
+      token:
+        $secret:
+          env: AZURE_PRIVATE_TOKEN
 
 auth:
   providers:
@@ -209,3 +240,33 @@ auth:
         tenantId:
           $secret:
             env: AUTH_MICROSOFT_TENANT_ID
+costInsights:
+  engineerCost: 200000
+  products:
+    computeEngine:
+      name: Compute Engine
+      icon: compute
+    cloudDataflow:
+      name: Cloud Dataflow
+      icon: data
+    cloudStorage:
+      name: Cloud Storage
+      icon: storage
+    bigQuery:
+      name: Big Query
+      icon: search
+  metrics:
+    dailyCost:
+      name: Your Company's Daily Cost
+    DAU:
+      name: Cost Per DAU
+homepage:
+  clocks:
+    - label: UTC
+      timzone: UTC
+    - label: NYC
+      timezone: 'America/New_York'
+    - label: STO
+      timezone: 'Europe/Stockholm'
+    - label: TYO
+      timezone: 'Asia/Tokyo'

contrib/docker/multi-stage-frontend/Dockerfile

@@ -1,4 +1,4 @@
-FROM node:12 AS build
+FROM node:12-buster AS build
 
 RUN mkdir /app
 COPY . /app

docs/FAQ.md

@@ -86,7 +86,7 @@ well-known tech and a large flora of components.
 
 ### What technology does Backstage use?
 
-The code base is a large-scale React application that uses TypeScript. For
+The codebase is a large-scale React application that uses TypeScript. For
 [Phase 2](https://github.com/spotify/backstage#project-roadmap), we plan to use
 Node.js and GraphQL.
 
@@ -132,20 +132,19 @@ 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
 [a plugin suggestion](https://github.com/spotify/backstage/issues/new/choose)
 and describe what your plugin will do. This will help coordinate our
-contributors' efforts and avoid duplicating existing functionality. In the
-future, we will create
-[a plugin gallery](https://github.com/spotify/backstage/issues/260) where people
-can browse and search for all available plugins.
+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
 technical documentation. Our philosophy at Spotify is to treat "docs like code",
 where you write documentation using the same workflow as you write your code.
-This makes it easier to create, find, and update documentation. We hope to
-release
-[the open source version](https://github.com/spotify/backstage/issues/687) in
-the future. (See also:
+This makes it easier to create, find, and update documentation.
+[TechDocs is now open source.](https://backstage.io/docs/features/techdocs/techdocs-overview)
+(See also:
 "[Will Spotify's internal plugins be open sourced, too?](#will-spotifys-internal-plugins-be-open-sourced-too)"
 above)
 
@@ -205,7 +204,7 @@ Please report sensitive security issues via Spotify's
 ### Does Backstage collect any information that is shared with Spotify?
 
 No. Backstage does not collect any telemetry from any third party using the
-platform. Spotify, and the open source community, does have access to
+platform. Spotify, and the open source community, do have access to
 [GitHub Insights](https://github.com/features/insights), which contains
 information such as contributors, commits, traffic, and dependencies. Backstage
 is an open platform, but you are in control of your own data. You control who

docs/api/utility-apis.md

@@ -97,7 +97,7 @@ app, and the app itself.
 
 ### Core APIs
 
-Starting with the Backstage core library, it provides implementation for all of
+Starting with the Backstage core library, it provides implementations for all of
 the core APIs. The core APIs are the ones exported by `@backstage/core`, such as
 the `errorApiRef` and `configApiRef`. You can find a full list of them
 [here](../reference/utility-apis/README.md).
@@ -113,7 +113,7 @@ While doing so they should usually also provide default implementations of their
 own APIs, for example, the `catalog` plugin exports `catalogApiRef`, and also
 supplies a default `ApiFactory` of that API using the `CatalogClient`. There is
 one restriction to plugin-provided API Factories: plugins may not supply
-factories for core APIs, trying to do so will cause the app to crash.
+factories for core APIs, trying to do so will cause the app to refuse to start.
 
 Plugins supply their APIs through the `apis` option of `createPlugin`, for
 example:
@@ -248,8 +248,8 @@ directly tied to React.
 The indirection provided by Utility APIs also makes it straightforward to test
 components that depend on APIs, and to provide a standard common development
 environment for plugins. A proper test wrapper with mocked API implementations
-is not yet ready, but it will provided as a part of `@backstage/test-utils`. It
-will provide mocked variants of APIs, with additional methods for asserting a
+is not yet ready, but it will be provided as a part of `@backstage/test-utils`.
+It will provide mocked variants of APIs, with additional methods for asserting a
 component's interaction with the API.
 
 The common development environment for plugins is included in

docs/architecture-decisions/adr002-default-catalog-file-format.md

@@ -22,7 +22,7 @@ This ADR describes the default format of these descriptor files.
 
 ### Inspiration
 
-Internally at Spotify, a home grown software catalog system is used heavily and
+Internally at Spotify, a homegrown software catalog system is used heavily and
 forms a core part of Backstage and other important pieces of the infrastructure.
 The user experience, learnings and certain pieces of metadata from that catalog
 are being carried over to the open source effort.
@@ -40,7 +40,7 @@ triggers from the version control system, etc.
 
 Each file describes one or more entities in accordance with the
 [Backstage System Model](https://github.com/spotify/backstage/issues/390). All
-of these entities have a common stucture and nomenclature, and they are stored
+of these entities have a common structure and nomenclature, and they are stored
 in the software catalog from which they then can be queried.
 
 Entities have distinct names, and they may reference each other by those names.

docs/architecture-decisions/adr003-avoid-default-exports.md

@@ -44,7 +44,7 @@ A summary:
   name each.
 
 Using named exports helps prevent needing to rename symbols, which has myriad
-benefts. A few are:
+benefits. A few are:
 
 - IDE tools like "Find All References" and "Go To Definition" function
 - Manual codebase searching ("grep", etc) is easier with a unique symbol

docs/architecture-decisions/adr004-module-export-structure.md

@@ -22,8 +22,8 @@ or
 We currently do not use any pattern for how to structure exports. There is a mix
 of package-level re-exports deep into the directory tree, shallow re-exports for
 each directory, exports using `*` and explicit lists of each symbol, etc. The
-mix and lack of predictability makes it difficult to reason about the boundaries
-of a module, and for example knowing whether is is safe to export a symbol in a
+mix and lack of predictability make it difficult to reason about the boundaries
+of a module, and for example knowing whether it is safe to export a symbol in a
 given file.
 
 ## Decision

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

@@ -13,7 +13,7 @@ with next to no benefits in combination with a few downsides.
 The main reasons were:
 
 - **children props** were implicitly added
-- **Generic Type** were not supported on children
+- **Generic Type** was not supported on children
 
 Read more about the removal in
 [this PR](https://github.com/facebook/create-react-app/pull/8177).
@@ -25,7 +25,7 @@ should be avoided in our codebase when adding new code.
 
 Here is an example:
 
-```ts
+```typescript
 /* Avoid this: */
 type BadProps = { text: string };
 const BadComponent: FC<BadProps> = ({ text, children }) => (

docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md

@@ -11,7 +11,7 @@ tests, unit tests to e2e tests always have their own implementation of mocking
 these requests. There's been traction in the outer community towards using this
 library to mock network requests by using an express style declaration for
 routes. react-testing-library suggests using this library instead of mocking
-fetch directly wether this be in a browser or in node.
+fetch directly whether this be in a browser or in node.
 
 https://github.com/mswjs/msw
 

docs/architecture-decisions/adr008-default-catalog-file-name.md

@@ -7,7 +7,7 @@ description: Architecture Decision Record (ADR) log on Default Catalog File Name
 ## Background
 
 While the spec for the catalog file format is well described in
-[ADR002](./adr002-default-catalog-file-format.md), guidance was note provided as
+[ADR002](./adr002-default-catalog-file-format.md), guidance was not provided as
 to the name of the catalog file.
 
 Following discussion in
@@ -23,4 +23,4 @@ catalog-info.yaml
 ```
 
 This name is a default, **not a requirement**. The catalog file will work with
-Backstage irregardless of its name.
+Backstage regardless of its name.

docs/architecture-decisions/adr009-entity-references.md

@@ -0,0 +1,69 @@
+---
+id: adrs-adr009
+title: ADR009: Entity References
+description: Architecture Decision Record (ADR) log on Entity References
+---
+
+## Background
+
+While the spec for the catalog file format is well described in
+[ADR002](./adr002-default-catalog-file-format.md), guidance was not provided as
+to how one is expected to express references to other entities in the catalog.
+There was also some confusion on how to reference entities in URLs in the
+Backstage frontend.
+
+Following discussion in
+[Issue 1947](https://github.com/spotify/backstage/issues/1947), a decision was
+made.
+
+## Entity References in YAML files
+
+The textual format, as written by humans, to reference entities by name is on
+the following form, where square brackets denote optionality:
+
+```
+[<kind>:][<namespace>/]<name>
+```
+
+That is, it is composed of between one and three parts in this specific order,
+without any additional encoding, with those exact separator characters.
+Optionality of `kind` and `namespace` are contextual, and they may or may not
+have default contextual fallback values.
+
+When that format is insufficient or when machine made interchange formats wish
+to express such relations in a more expressive form, a nested structure on the
+following form can be used:
+
+```yaml
+kind: <kind>
+namespace: <namespace>
+name: <name>
+```
+
+Of these, only `name` is always required. Optionality of `kind` and `namespace`
+are contextual, and they may or may not have default contextual fallback values.
+All other possible key values in this structure are reserved for future use.
+
+A system or user wanting to express a full entity name that is always valid,
+shall supply the entire triplet whether using the string form or the compound
+form.
+
+A full description of the format can be found
+[in the documentation](https://backstage.io/docs/features/software-catalog/references).
+
+## Entity References in URLs
+
+Where entities are referenced by name in the Backstage frontend, the URL
+containing the reference shall take the following form:
+
+```
+:namespace/:kind/:name
+```
+
+All three parts are required under all circumstances. The default value for the
+`namespace` in the catalog is the string `"default"`, if the entity does not
+specify one explicitly in `metadata.namespace`.
+
+This means that we do not encourage the string form of entity references to be
+used as a single URL segment, due to the use of URL-unsafe characters leading to
+possible risk, confusion, and uglier URLs.

docs/auth/add-auth-provider.md

@@ -229,9 +229,10 @@ name.
 
 ### Test the new provider
 
-You can `curl -i localhost:7000/auth/providerA/start` and which should provide a
-`302` redirect with a `Location` header. Paste the url from that header into a
-web browser and you should be able to trigger the authorization flow.
+You can `curl -i localhost:7000/api/auth/providerA/start` and which should
+provide a `302` redirect with a `Location` header. Paste the url from that
+header into a web browser and you should be able to trigger the authorization
+flow.
 
 ---
 

docs/auth/index.md

@@ -6,7 +6,7 @@ description: Documentation on User Authentication and Authorization in Backstage
 
 ## Summary
 
-The purpose of the Auth APIs in Backstage are to identify the user, and to
+The purpose of the Auth APIs in Backstage is to identify the user, and to
 provide a way for plugins to request access to 3rd party services on behalf of
 the user (OAuth). This documentation focuses on the implementation of that
 solution and how to extend it. For documentation on how to consume the Auth APIs

docs/auth/oauth.md

@@ -52,7 +52,7 @@ in a new popup window that is opened by the app. By using a popup-based flow it
 is possible to request authentication at any point in the app, without requiring
 a redirect. Because of this there is no need to ask for all scopes upfront, or
 interrupt the app with a redirect and forcing plugin authors to take care in
-restoring state after a redirect has been make. All in all it makes it much
+restoring state after a redirect has been made. All in all it makes it much
 easier to make authenticated requests inside a plugin.
 
 ## OAuth Flow
@@ -67,7 +67,7 @@ Component and APIs can request Access or ID Tokens from any available Auth
 provider. If there already exists a cached fresh token that covers (at least)
 the requested scopes, it will be returned immediately. If the OAuth provider
 implements token refreshes, this check will also trigger a token refresh attempt
-if no session is a available.
+if no session is available.
 
 If new scopes are requested, or the user is not yet logged in with that
 provider, a dialog is shown informing the user that they need to log in with the

docs/features/software-catalog/configuration.md

@@ -11,36 +11,56 @@ tasks, such as reading raw entity data from a remote source, parsing it,
 transforming it, and validating it. These processors are configured under the
 `catalog.processors` key.
 
-### Processor: github
+### Processor: url
 
-The `github` processor is responsible for fetching entity data from files on
-GitHub or GitHub Enterprise. The configuration for this processor lives under
-`catalog.processors.github`. Example:
+The `url` processor is responsible for fetching entity data from files in any
+external provider like GitHub, GitLab, Bitbucket, etc. The configuration of this
+processor lives under the top-level `integrations` key, as it is used by other
+parts of Backstage too.
 
 ```yaml
-catalog:
-  processors:
-    github:
-      providers:
-        - target: https://github.com
-          token:
-            $secret:
-              env: GITHUB_PRIVATE_TOKEN
-        - target: https://ghe.example.net
-          apiBaseUrl: https://ghe.example.net/api/v3
-          rawBaseUrl: https://ghe.example.net/raw
-          token:
-            $secret:
-              env: GHE_PRIVATE_TOKEN
+integrations:
+  github:
+    - host: github.com
+      token:
+        $secret:
+          env: GITHUB_TOKEN
+    - host: ghe.example.net
+      apiBaseUrl: https://ghe.example.net/api/v3
+      rawBaseUrl: https://ghe.example.net/raw
+      token:
+        $secret:
+          env: GHE_TOKEN
+  gitlab:
+    - host: gitlab.com
+      token:
+        $secret:
+          env: GITLAB_TOKEN
+  bitbucket:
+    - host: bitbucket.org
+      username:
+        $secret:
+          env: BITBUCKET_USERNAME
+      appPassword:
+        $secret:
+          env: BITBUCKET_APP_PASSWORD
+  azure:
+    - host: dev.azure.com
+      token:
+        $secret:
+          env: AZURE_TOKEN
 ```
 
-The main subkey is `providers`, where you can list the various GitHub compatible
-providers you want to be able to fetch data from. Each entry is a structure with
-up to four elements:
+Each key under `integrations` is a separate configuration for each external
+provider. The providers each have their own configuration, so let's look at the
+GitHub section as an example.
 
-- `target` (required): The string prefix of the location target that you want to
-  match on, with no trailing slash. For GitHub, it should be exactly
-  `https://github.com`.
+Directly under the `github` key is a list of provider configurations, where you
+can list the various GitHub compatible providers you want to be able to fetch
+data from. Each entry is a structure with up to four elements:
+
+- `host` (optional): The host of the location target that you want to match on.
+  The default host is `github.com`.
 - `token` (optional): An authentication token as expected by GitHub. If
   supplied, it will be passed along with all calls to this provider, both API
   and raw. If it is not supplied, anonymous access will be used.
@@ -74,7 +94,7 @@ the catalog under the `catalog.locations` key, for example:
 ```yaml
 catalog:
   locations:
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
 ```
 
@@ -97,7 +117,7 @@ catalog:
     - allow: [Component, API, Location, Template]
 
   locations:
-    - type: github
+    - type: url
       target: https://github.com/org/example/blob/master/org-data.yaml
       rules:
         - allow: [Group]

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

@@ -22,6 +22,8 @@ humans. However, the structure and semantics is the same in both cases.
 - [Kind: Component](#kind-component)
 - [Kind: Template](#kind-template)
 - [Kind: API](#kind-api)
+- [Kind: Group](#kind-group)
+- [Kind: User](#kind-user)
 
 ## Overall Shape Of An Entity
 
@@ -571,3 +573,167 @@ group of people in an organizational structure.
 
 The definition of the API, based on the format defined by `spec.type`. This
 field is required.
+
+## Kind: Group
+
+Describes the following entity kind:
+
+| Field        | Value                   |
+| ------------ | ----------------------- |
+| `apiVersion` | `backstage.io/v1alpha1` |
+| `kind`       | `Group`                 |
+
+A group describes an organizational entity, such as for example a team, a
+business unit, or a loose collection of people in an interest group. Members of
+these groups are modeled in the catalog as kind [`User`](#kind-user).
+
+Descriptor files for this kind may look as follows.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Group
+metadata:
+  name: infrastructure
+  description: The infra business unit
+spec:
+  type: business-unit
+  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)
+shape, this kind has the following structure.
+
+### `apiVersion` and `kind` [required]
+
+Exactly equal to `backstage.io/v1alpha1` and `Group`, respectively.
+
+### `spec.type` [required]
+
+The type of group as a string, e.g. `team`. There is currently no enforced set
+of values for this field, so it is left up to the adopting organization to
+choose a nomenclature that matches their org hierarchy.
+
+Some common values for this field could be:
+
+- `team`
+- `business-unit`
+- `product-area`
+- `root` - as a common virtual root of the hierarchy, if desired
+
+### `spec.parent` [optional]
+
+The immediate parent group in the hierarchy, if any. Not all groups must have a
+parent; the catalog supports multi-root hierarchies. Groups may however not have
+more than one parent.
+
+This field is an
+[entity reference](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,
+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
+points to this group). 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.
+
+### `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:
+
+| Field        | Value                   |
+| ------------ | ----------------------- |
+| `apiVersion` | `backstage.io/v1alpha1` |
+| `kind`       | `User`                  |
+
+A user describes a person, such as an employee, a contractor, or similar. Users
+belong to [`Group`](#kind-group) entities in the catalog.
+
+These catalog user entries are connected to the way that authentication within
+the Backstage ecosystem works. See the [auth](https://backstage.io/docs/auth)
+section of the docs for a discussion of these concepts.
+
+Descriptor files for this kind may look as follows.
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: User
+metadata:
+  name: jdoe
+spec:
+  profile:
+    displayName: Jenny Doe
+    email: jenny-doe@example.com
+    picture: https://example.com/staff/jenny-with-party-hat.jpeg
+  memberOf: [team-b, employees]
+```
+
+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 `User`, respectively.
+
+### `spec.profile` [optional]
+
+Optional profile information about the user, mainly for display purposes. All
+fields of this structure are also optional. The email would be a primary email
+of some form, that the user 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 user,
+and that a browser could fetch and render on a profile page or similar.
+
+### `spec.memberOf` [required]
+
+The list of groups that the user is a direct member of (i.e., no transitive
+memberships are listed here). The list must be present, but may be empty if the
+user is not member of any 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.

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

@@ -16,11 +16,9 @@ Backstage natively supports tracking of the following component
 ![](../../assets/software-catalog/bsc-extend.png)
 
 Since these types are likely not the only kind of software you will want to
-track in Backstage, it is possible to
-
-It is possible to add your own software types that fits 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.
+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.
 
 ## Adding a new type
 
@@ -30,7 +28,7 @@ catalog.
 ## The Other type
 
 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 advice against this; firstly,
+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

docs/features/software-catalog/index.md

@@ -84,13 +84,13 @@ registered in the catalog.
 ### Static catalog configuration
 
 In addition to manually registering components, it is also possible to register
-components though [static configuration](../../conf/index.md). For example, the
+components through [static configuration](../../conf/index.md). For example, the
 above example can be added using the following configuration:
 
 ```yaml
 catalog:
   locations:
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
 ```
 

docs/features/software-catalog/installation.md

@@ -166,21 +166,21 @@ our example templates through static configuration. Add the following to the
 catalog:
   locations:
     # Backstage Example Component
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/playback-order-component.yaml
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/podcast-api-component.yaml
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/queue-proxy-component.yaml
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/searcher-component.yaml
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/playback-lib-component.yaml
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/www-artist-component.yaml
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/shuffle-api-component.yaml
 ```
 

docs/features/software-catalog/references.md

@@ -0,0 +1,104 @@
+---
+id: references
+title: Entity References
+description: How to express references between entities
+---
+
+Entities commonly have a need to reference other entities. For example, a
+[Component](descriptor-format.md#kind-component) entity may want to declare who
+its owner is by mentioning a Group or User entity, and a User entity may want to
+declare what Group entities it is a member of. This article describes how to
+write those references in your yaml entity declaration files.
+
+Each entity in the catalog is uniquely identified by the triplet of its
+[kind](descriptor-format.md#apiversion-and-kind-required),
+[namespace](descriptor-format.md#namespace-optional), and
+[name](descriptor-format.md#name-required). But that's a lot to type out
+manually, and in a lot of circumstances, both the kind and the namespace are
+fixed, or possible to deduce, or could have sane default values. So in order to
+help the writer, the catalog has a few tricks up its sleeve.
+
+Each reference can be expressed in one of two ways: as a compact string, or as a
+compound reference structure.
+
+## String References
+
+This is the most common alternative, that should be used in almost all
+circumstances.
+
+The string is on the form `[<kind>:][<namespace>/]<name>`, that is, it is
+composed of between one and three parts in this specific order, without any
+additional encoding:
+
+- Optionally, the kind, followed by a colon
+- Optionally, the namespace, followed by a forward slash
+- The name
+
+The name is always required. Depending on the context, you may be able to leave
+out the kind and/or namespace. If you do, it is contextual what values will be
+used, and the relevant documentation should specify which rule applies where.
+All strings are case insensitive.
+
+```yaml
+# Example:
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: petstore
+  namespace: external-systems
+  description: Petstore
+spec:
+  type: service
+  lifecycle: experimental
+  owner: group:pet-managers
+  implementsApis:
+    - petstore
+    - internal/streetlights
+    - hello-world
+```
+
+The field `spec.owner` is a reference. In this case, the string
+`group:pet-managers` was given by the user. That means that the kind is `Group`,
+the namespace is left out, and the name is `pet-managers`. In this context, the
+namespace was chosen to fall back to the value `default` by the code that parsed
+the reference, so the end result is that we expect to find another entity in the
+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
+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
+originating entity (`external-systems` here). So the three references
+essentially expand to `api:external-systems/petstore`,
+`api:internal/streetlights`, and `api:external-systems/hello-world`. We expect
+there to exist three API kind entities in the catalog matching those references.
+
+## Compound References
+
+This is a more verbose version of a reference, where each part of the
+kind-namespace-name triplet is expressed as a field in a structure. This format
+can be used where necessary, such as if either of the three elements contains
+colons or forward slashes. Avoid using it where possible, since it is harder to
+read and write for humans.
+
+```yaml
+# Example:
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: petstore
+  description: Petstore
+spec:
+  type: service
+  lifecycle: experimental
+  owner:
+    kind: Group
+    name: aegis-imports/pet-managers
+```
+
+In this example, the `spec.owner` has been broken apart since the name was
+complex. The kind happened to be written with an uppercase letter G, which also
+works. The namespace was left out just like in the string version above, which
+is handled identically.

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

@@ -41,6 +41,27 @@ expecting a two-item array out of it. The format of the target part is
 type-dependent and could conceivably even be an empty string, but the separator
 colon is always present.
 
+### backstage.io/definition-at-location
+
+```yaml
+# Example
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: petstore
+  annotations:
+    backstage.io/definition-at-location: 'url:https://petstore.swagger.io/v2/swagger.json'
+spec:
+  type: openapi
+```
+
+This annotation allows to fetch an API definition from another location, instead
+of wrapping the API definition inside the definition field. This allows to
+easily consume existing API definition. The definition is fetched during
+ingestion by a processor and included in the entity. It is updated on every
+refresh. The annotation contains a location reference string that contains the
+location processor type and the target.
+
 ### backstage.io/techdocs-ref
 
 ```yaml
@@ -79,13 +100,50 @@ metadata:
 ```
 
 The value of this annotation is the so-called slug that identifies a project on
-[GitHub](https://github.com) that is related to this entity. It is on the format
+[GitHub](https://github.com) (either the public one, or a private GitHub
+Enterprise installation) that is related to this entity. It is on the format
 `<organization>/<project>`, and is the same as can be seen in the URL location
 bar of the browser when viewing that project.
 
 Specifying this annotation will enable GitHub related features in Backstage for
 that entity.
 
+### github.com/team-slug
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    github.com/team-slug: spotify/backstage-core
+```
+
+The value of this annotation is the so-called slug that identifies a team on
+[GitHub](https://github.com) (either the public one, or a private GitHub
+Enterprise installation) that is related to this entity. It is on the format
+`<organization>/<team>`, and is the same as can be seen in the URL location bar
+of the browser when viewing that team.
+
+This annotation can be used on a [Group entity](descriptor-format.md#kind-group)
+to note that it originated from that team on GitHub.
+
+### github.com/user-login
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    github.com/user-login: freben
+```
+
+The value of this annotation is the so-called login that identifies a user on
+[GitHub](https://github.com) (either the public one, or a private GitHub
+Enterprise installation) that is related to this entity. It is on the format
+`<username>`, and is the same as can be seen in the URL location bar of the
+browser when viewing that user.
+
+This annotation can be used on a [User entity](descriptor-format.md#kind-user)
+to note that it originated from that user on GitHub.
+
 ### sentry.io/project-slug
 
 ```yaml

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

@@ -5,7 +5,7 @@ description: Documentation on Adding your own Templates
 ---
 
 Templates are stored in the **Service Catalog** under a kind `Template`. The
-minimum that the a template skeleton needs is a `template.yaml` but it would be
+minimum that the template skeleton needs is a `template.yaml` but it would be
 good to also have some files in there that can be templated in.
 
 A simple `template.yaml` definition might look something like this:
@@ -30,7 +30,7 @@ spec:
   templater: cookiecutter
   # what does this template create
   type: website
-  # if the template is not in the current directory where this definition is kept then specfiy
+  # if the template is not in the current directory where this definition is kept then specify
   path: './template'
   # the schema for the form which is displayed in the frontend.
   # should follow JSON schema for forms: https://jsonforms.io/
@@ -66,7 +66,7 @@ for example
 ```yaml
 catalog:
   locations:
-    - type: github
+    - type: url
       target: https://github.com/spotify/cookiecutter-golang/blob/master/template.yaml
       rules:
         - allow: [Template]
@@ -88,7 +88,7 @@ running:
 ```sh
 curl \
   --location \
-  --request POST 'localhost:7000/catalog/locations' \
+  --request POST 'localhost:7000/api/catalog/locations' \
   --header 'Content-Type: application/json' \
   --data-raw "{\"type\": \"file\", \"target\": \"${YOUR PATH HERE}/template.yaml\"}"
 ```
@@ -98,7 +98,7 @@ If loading from a Git location, you can run the following
 ```sh
 curl \
   --location \
-  --request POST 'localhost:7000/catalog/locations' \
+  --request POST 'localhost:7000/api/catalog/locations' \
   --header 'Content-Type: application/json' \
   --data-raw "{\"type\": \"github\", \"target\": \"https://${YOUR GITHUB REPO}blob/master/${PATH TO FOLDER}/template.yaml\"}"
 ```
@@ -107,7 +107,7 @@ This should then have added the catalog, and also should now be listed under the
 create page at http://localhost:3000/create.
 
 The `type` field which is chosen in the request to add the `template.yaml` to
-the Service Catalog here, will be come the `PreparerKey` which will be used to
+the Service Catalog here, will become the `PreparerKey` which will be used to
 select the `Preparer` when creating a job.
 
 ### Adding form values in the Scaffolder Wizard

docs/features/software-templates/extending/create-your-own-preparer.md

@@ -17,7 +17,7 @@ location protocols:
 These two are added to the `PreparersBuilder` and then passed into the
 `createRouter` function of the `@spotify/plugin-scaffolder-backend`
 
-An full example backend can be found
+A full example backend can be found
 [here](https://github.com/spotify/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts),
 but it looks something like the following
 
@@ -88,7 +88,7 @@ Some good examples exist here:
 - https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/stages/prepare/file.ts
 - https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/stages/prepare/github.ts
 
-### Registerinng your own Preparer
+### Registering your own Preparer
 
 You can register the preparer that you have created with the `PreparerBuilder`
 by using the `PreparerKey` from the Catalog, for example like this:
@@ -98,4 +98,4 @@ const preparers = new Preparers();
 preparers.register('gcs', new GoogleCloudStoragePreparer());
 ```
 
-And then pass this in to the `createRouter` function.
+And then pass this into the `createRouter` function.

docs/features/software-templates/extending/create-your-own-publisher.md

@@ -8,10 +8,10 @@ Publishers are responsible for pushing and storing the templated skeleton after
 the values have been templated by the `Templater`. See
 [Create your own templater](./create-your-own-templater.md) for more info.
 
-They receive a directory or location where the templater has sucessfully run and
-is now ready to store somewhere. They also are given some other options which
-are sent from the frontend, such as the `storePath` which is a string of where
-the frontend thinks we should save this templated folder.
+They receive a directory or location where the templater has successfully run
+and is now ready to store somewhere. They also are given some other options
+which are sent from the frontend, such as the `storePath` which is a string of
+where the frontend thinks we should save this templated folder.
 
 Currently we provide the following `publishers`:
 

docs/features/software-templates/extending/create-your-own-templater.md

@@ -147,4 +147,4 @@ const templaters = new Templaters();
 templaters.register('handlebars', new HandlebarsTemplater());
 ```
 
-And then pass this in to the `createRouter` function.
+And then pass this into the `createRouter` function.

docs/features/software-templates/extending/index.md

@@ -11,13 +11,13 @@ You're at the right place.
 This guide is going to take you through how the Scaffolder in Backstage works.
 We'll dive into some jargon and run through what's going on in the backend to be
 able to create these templates. There's also more guides that you might find
-useful at the bottom of this document. At it's core, theres 3 simple stages.
+useful at the bottom of this document. At its core, there are 3 simple stages.
 
 1. Pick a skeleton
 2. Template some variables into the skeleton
 3. Send the templated skeleton somewhere
 
-These three steps are translated to the folllowing stages under the hood in the
+These three steps are translated to the following stages under the hood in the
 scaffolder that you will need to know:
 
 1. Prepare
@@ -38,7 +38,7 @@ the router to pick the correct `Preparer` to run for the `Template` entity.
 
 **Templater** - The templater is responsible for actually running the chosen
 templater on top of the previously returned temporary directory from the
-**Preprarer**. We advise making these Docker containers as it can keep all
+**Preparer**. We advise making these Docker containers as it can keep all
 dependencies--for example Cookiecutter--self contained and not a dependency on
 the host machine.
 
@@ -82,7 +82,7 @@ Once that has been posted, a job will be setup with different stages, and the
 job processor will complete each stage before moving onto the next stage, whilst
 collecting logs and mutating the running job.
 
-Here's some futher reading that you might find useful:
+Here's some further reading that you might find useful:
 
 - [Adding your own Template](../adding-templates.md)
 - [Creating your own Templater](./create-your-own-templater.md)

docs/features/software-templates/installation.md

@@ -191,13 +191,13 @@ our example templates through static configuration. Add the following to the
 catalog:
   locations:
     # Backstage Example Templates
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/react-ssr-template/template.yaml
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/springboot-grpc-template/template.yaml
-    - type: github
+    - type: url
       target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/create-react-app/template.yaml
-    - type: github
+    - type: url
       target: https://github.com/spotify/cookiecutter-golang/blob/master/template.yaml
 ```
 
@@ -217,6 +217,11 @@ The Github access token is retrieved from environment variables via the config.
 The config file needs to specify what environment variable the token is
 retrieved from. Your config should have the following objects.
 
+You can configure who can see the new repositories that the scaffolder creates
+by specifying `visibility` option. Valid options are `public`, `private` and
+`internal`. `internal` options is for GitHub Enterprise clients, which means
+public within the organization.
+
 #### Gitlab
 
 For Gitlab, we currently support the configuration of the GitLab publisher and
@@ -238,10 +243,23 @@ scaffolder:
           env: SCAFFOLDER_GITLAB_PRIVATE_TOKEN
 ```
 
-You can configure who can see the new repositories that the scaffolder creates
-by specifying `visibility` option. Valid options are `public`, `private` and
-`internal`. `internal` options is for GitHub Enterprise clients, which means
-public within the organization.
+#### Azure DevOps
+
+For Azure DevOps we support both the preparer and publisher stage with the
+configuration of a private access token (PAT). For the publisher it's also
+required to define the base URL for the client to connect to the service. This
+will hopefully support on-prem installations as well but that has not been
+verified.
+
+```yaml
+scaffolder:
+  azure:
+    baseUrl: https://dev.azure.com/{your-organization}
+    api:
+      token:
+        $secret:
+          env: AZURE_PRIVATE_TOKEN
+```
 
 ### Running the Backend
 

docs/features/techdocs/FAQ.md

@@ -11,14 +11,15 @@ This page answers frequently asked questions about [TechDocs](README.md).
 
 - [What static site generator is TechDocs using?](#what-static-site-generator-is-techdocs-using)
 - [What is the mkdocs-techdocs-core plugin?](#what-is-the-mkdocs-techdocs-core-plugin)
-- [Does TechDocs support file formats other than Markdown (e.g. rst, asciidoc)?](#does-techdocs-support-file-formats-other-than-markdown-eg-rst-asciidoc-)
+- [Does TechDocs support file formats other than Markdown (e.g. RST, AsciiDoc)?](#does-techdocs-support-file-formats-other-than-markdown-eg-rst-asciidoc-)
 
 #### What static site generator is TechDocs using?
 
 TechDocs is using [MkDocs](https://www.mkdocs.org/) to build project
 documentation under the hood. Documentation built with the
 [techdocs-container](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/README.md)
-is using the MkDocs Material Theme.
+is using the MkDocs
+[Material Theme](https://github.com/squidfunk/mkdocs-material).
 
 #### What is the mkdocs-techdocs-core plugin?
 
@@ -29,9 +30,9 @@ plugins (e.g.
 [MkDocs Monorepo Plugin](https://github.com/spotify/mkdocs-monorepo-plugin)) as
 well as a selection of Python Markdown extensions that TechDocs supports.
 
-#### Does TechDocs support file formats other than Markdown (e.g. rst, asciidoc) ?
+#### Does TechDocs support file formats other than Markdown (e.g. RST, AsciiDoc) ?
 
 Not right now. We are currently using MkDocs to generate the documentation from
-source. So, they have to be in Markdown format. However, in future we want to
-support other alternatives to MkDocs. That will make it possible to use other
-file formats.
+source, so the files have to be in Markdown format. However, in the future we
+want to support other static site generators which will make it possible to use
+other file formats.

docs/features/techdocs/README.md

@@ -33,16 +33,17 @@ about TechDocs and the philosophy in its
 
 ## Project roadmap
 
-| Version                 | Description                                                                                                                         |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| [TechDocs V.0 ✅][v0]   | Read docs in Backstage - Enable anyone to get a reader experience working in Backstage. [See V.0 Use Cases.](#techdocs-v0)          |
-| [TechDocs V.1 ✅][v1]   | TechDocs end to end (alpha) - Alpha of TechDocs that you can use end to end - and contribute to. [See V.1 Use Cases.](#techdocs-v1) |
-| [TechDocs V.2 🔮⌛][v2] | Platform stability and compatibility improvements. [See V.2 Use Cases.](#techdocs-v2)                                               |
-| TechDocs V.3 🔮⌛       | Widget Architecture - TechDocs widget architecture available, so the community can create their own customized features.            |
+| Version                 | Description                                                                                                                                                 |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [TechDocs V.0 ✅][v0]   | Read docs in Backstage - Enable anyone to get a reader experience working in Backstage. [See V.0 Use Cases.](#techdocs-v0)                                  |
+| [TechDocs V.1 ✅][v1]   | TechDocs end to end (alpha) - Alpha of TechDocs that you can use end to end - and contribute to. [See V.1 Use Cases.](#techdocs-v1)                         |
+| [TechDocs V.2 🔮⌛][v2] | Easy adoption of TechDocs (whatever environment you have) [See V.2 Use Cases.](#techdocs-v2)                                                                |
+| [TechDocs V.3 🔮⌛][v3] | Build a widget (plugin) framework so that contributors can easily contribute features to TechDocs - that others can use. [See V.3 Use Cases.](#techdocs-v3) |
 
 [v0]: https://github.com/spotify/backstage/milestone/15
 [v1]: https://github.com/spotify/backstage/milestone/16
-[v2]: https://github.com/spotify/backstage/milestone/17
+[v2]: https://github.com/spotify/backstage/milestone/22
+[v3]: https://github.com/spotify/backstage/milestone/17
 
 <!-- TODO: Add link to milestone for v3 -->
 
@@ -59,26 +60,39 @@ about TechDocs and the philosophy in its
 - As a user I can run TechDocs locally and read documentation.
 - As a user I can create a docs folder in my entity project and add a reference
   in the entity configuration file (of the owning entity) to my documentation.
-  - Backstage will automatically build my documentation and serve it in
-    TechDocs.
-  - Documentation will be displayed under the docs tab in the service catalog.
+- Backstage will automatically build my documentation and serve it in TechDocs.
+- Documentation will be displayed under the docs tab in the service catalog.
 - As a user I can create a docs only repository that will be standalone from any
   other service.
 - As a user I can choose my own storage solution for the documentation (as
   example GCS/AWS/Azure etc)
 - As a user I can define my own API to interface my own documentation solution.
 
-#### TechDocs V.2
-
-Platform stability and compatibility improvements
+Extra platform stability and compatibility improvements:
 
 - As a user I can define the metadata generated for my documentation.
 - As a user I will be able to browse metadata from within my documentation in
   Backstage.
 
+#### TechDocs V.2
+
+We have a TechDocs that works end-to-end. The next step is to make it super easy
+for companies to adopt. This involves (something like) the following work items.
+
+- “Solidify” work and “Mkdocs stabilization” work that has come out of our Q3
+  end-to-end work.
+- Improve/simplify the get up and running process.
+- Introduce doc template Software Templates.
+- Enable companies to choose their own storage (S3 for example).
+- Enable companies to choose their own source code hosting provider (GitHub,
+  GitLab, and so).
+- Share how to plug in TechDocs to your own CI.
+
 #### TechDocs V.3
 
-more to come...
+Build a widget (plugin) framework so that contributors can easily contribute
+features to TechDocs - that others can use. And, also, so that we can easily
+migrate Spotify's existing TechDocs features to open source.
 
 ## Structure
 

docs/features/techdocs/concepts.md

@@ -25,7 +25,14 @@ MkDocs.
 
 [TechDocs Container](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/README.md)
 
-### TechDocs publisher (coming soon)
+### TechDocs publisher
+
+The `techdocs-backend` plugin currently comes with one publisher -
+`LocalPublish`.
+
+[TechDocs Backend](https://github.com/spotify/backstage/tree/master/plugins/techdocs-backend)
+
+More standalone publishers will come in the near future...
 
 ### TechDocs CLI
 

docs/features/techdocs/getting-started.md

@@ -13,7 +13,7 @@ If you haven't setup Backstage already, start
 ## Installing TechDocs
 
 TechDocs is provided with the Backstage application by default. If you want to
-set up TechDocs manually, keep follow the instructions below.
+set up TechDocs manually, keep following the instructions below.
 
 ### Adding the package
 
@@ -57,8 +57,8 @@ The default storage and request URLs:
 
 ```yaml
 techdocs:
-  storageUrl: http://localhost:7000/techdocs/static/docs
-  requestUrl: http://localhost:7000/techdocs/docs
+  storageUrl: http://localhost:7000/api/techdocs/static/docs
+  requestUrl: http://localhost:7000/api/techdocs/docs
 ```
 
 If you want `techdocs-backend` to manage building and publishing, you want

docs/features/techdocs/troubleshooting.md

@@ -0,0 +1,10 @@
+---
+id: troubleshooting
+title: Troubleshooting TechDocs
+sidebar_label: Troubleshooting
+description: Troubleshooting for TechDocs
+---
+
+- TechDocs will fail to clone your docs if you have a git config which overrides
+  the `https` protocol with `ssh` or something else. Make sure to remove your
+  git config locally when you try TechDocs.

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

@@ -38,6 +38,34 @@ 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.
 
+### Troubleshooting
+
+The create app command doesn't always work as expected, this is a collection of
+some of the commonly encountered issues and solutions.
+
+#### Couldn't find any versions for "file-saver"
+
+You may encounter the following error message:
+
+```text
+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
+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:
+
+```bash
+NPM_CONFIG_REGISTRY=https://registry.npmjs.org npx @backstage/create-app
+```
+
+#### Can't find Python executable "python"
+
+The install process may also fail if no Python installation is available. Python
+is commonly available in most systems already, but if it isn't you can head for
+example [here](https://www.python.org/downloads/) to install it.
+
 ### General folder structure
 
 Below is a simplified layout of the files and folders generated when creating an

docs/getting-started/index.md

@@ -24,9 +24,11 @@ Requests towards this repo.
 Backstage provides the `@backstage/create-app` package to scaffold standalone
 instances of Backstage. You will need to have
 [NodeJS](https://nodejs.org/en/download/) Active LTS Release installed
-(currently v12), and [yarn](https://classic.yarnpkg.com/en/docs/install). You
-will also need to have [Docker](https://docs.docker.com/engine/install/)
-installed to use some features like Software Templates and TechDocs.
+(currently v12), [yarn](https://classic.yarnpkg.com/en/docs/install) and
+[Python](https://www.python.org/downloads/) (although you likely have it
+already). You will also need to have
+[Docker](https://docs.docker.com/engine/install/) installed to use some features
+like Software Templates and TechDocs.
 
 Using `npx` you can then run the following to create an app in a chosen
 subdirectory of your current working directory:

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

@@ -42,7 +42,7 @@ of GitHub and run an initial build.
 
 ```bash
 # Start from your local development folder
-git clone git@github.com:spotify/backstage.git
+git clone --depth 1 git@github.com:spotify/backstage.git
 cd backstage
 
 # Fetch our dependencies and run an initial build

docs/openapi/definitions/auth.yaml

@@ -6,10 +6,10 @@ info:
 
     **Provided by `@backstage/auth-backend`.**
 
-    The purpose of the Auth APIs in Backstage are to identify the user, and to provide a way for plugins 
+    The purpose of the Auth APIs in Backstage are to identify the user, and to provide a way for plugins
     to request access to 3rd party services on behalf of that user.
 
-    The API is supplied with a list of providers - such as `Google` or `Github` - and will add the endpoints 
+    The API is supplied with a list of providers - such as `Google` or `Github` - and will add the endpoints
     described below to each of those providers.
 
     Read more about [User Authentication and Authorization in Backstage](https://github.com/spotify/backstage/blob/master/docs/auth/overview.md).
@@ -21,7 +21,7 @@ externalDocs:
   description: Backstage official documentation
   url: https://github.com/spotify/backstage/blob/master/docs/README.md
 servers:
-  - url: http://localhost:7000/auth/
+  - url: http://localhost:7000/api/auth/
 tags:
   - name: provider
     description: List of endpoints per provider

docs/overview/architecture-overview.md

@@ -4,6 +4,23 @@ title: Architecture overview
 description: Documentation on Architecture overview
 ---
 
+## Terminology
+
+Backstage is constructed out of three parts. We separate Backstage in this way
+because we see three groups of contributors that work with Backstage in three
+different ways.
+
+- Core - Base functionality built by core developers in the open source project.
+- App - The app is an instance of a Backstage app that is deployed and tweaked.
+  The app ties together core functionality with additional plugins. The app is
+  built and maintained by app developers, usually a productivity team within a
+  company.
+- Plugins - Additional functionality to make your Backstage app useful for your
+  company. Plugins can be specific to a company or open sourced and reusable. At
+  Spotify we have over 100 plugins built by over 50 different teams. It has been
+  very powerful to get contributions from various infrastructure teams added
+  into a single unified developer experience.
+
 ## Overview
 
 The following diagram shows how Backstage might look when deployed inside a

docs/overview/architecture-terminology.md

@@ -1,20 +0,0 @@
----
-id: architecture-terminology
-title: Architecture terminology
-description: Documentation on Architecture terminology
----
-
-Backstage is constructed out of three parts. We separate Backstage in this way
-because we see three groups of contributors that work with Backstage in three
-different ways.
-
-- Core - Base functionality built by core devs in the open source project.
-- App - The app is an instance of a Backstage app that is deployed and tweaked.
-  The app ties together core functionality with additional plugins. The app is
-  built and maintained by app developers, usually a productivity team within a
-  company.
-- Plugins - Additional functionality to make your Backstage app useful for your
-  company. Plugins can be specific to a company or open sourced and reusable. At
-  Spotify we have over 100 plugins built by over 50 different teams. It has been
-  very powerful to get contributions from various infrastructure teams added
-  into a single unified developer experience.

docs/overview/background.md

@@ -1,7 +1,8 @@
 ---
 id: background
 title: The Spotify Story
-description: Documentation on Background and Story behind making of Backstage
+description: Backstage was born out of necessity at Spotify. We found that as we grew, our
+infrastructure was becoming more fragmented, our engineers less productive.
 ---
 
 Backstage was born out of necessity at Spotify. We found that as we grew, our
@@ -29,3 +30,9 @@ building a new microservice using an automated template in Backstage. Create,
 maintain, and find the documentation for all that software in Backstage.
 
 One place for everything. Accessible to everyone.
+
+Backstage was originally built by Spotify and then donated to the CNCF.
+Backstage is currently in the Sandbox phase. Read the announcement
+[here](https://backstage.io/blog/2020/09/23/backstage-cncf-sandbox).
+
+<img src="https://backstage.io/img/cncf-white.svg" width="400" />

docs/overview/roadmap.md

@@ -27,10 +27,11 @@ We have divided the project into three high-level _phases_:
   With a single catalog, Backstage makes it easy for a team to manage ten
   services — and makes it possible for your company to manage thousands of them.
 
-- 🐇 **Phase 3:** Ecosystem (later) - Everyone's infrastructure stack is
-  different. By fostering a vibrant community of contributors we hope to provide
-  an ecosystem of Open Source plugins/integrations that allows you to pick the
-  tools that match your stack.
+- 🐇 **Phase 3:** Ecosystem (ongoing, see
+  [Plugin Marketplace](https://backstage.io/plugins)) - Everyone's
+  infrastructure stack is different. By fostering a vibrant community of
+  contributors we hope to provide an ecosystem of Open Source
+  plugins/integrations that allows you to pick the tools that match your stack.
 
 ## Detailed roadmap
 
@@ -53,31 +54,24 @@ guidelines to get started.
   it much easier to see how a plugin can be built that integrates with the
   Backstage Service Catalog.
 
+- **[Kubernetes support](https://github.com/spotify/backstage/milestone/20)** -
+  Native support for Kubernetes, making it easier for developers to see and
+  manage their services running in k8s.
+
+- **[Helm charts](https://github.com/spotify/backstage/issues/2540)** - Provide
+  Helm charts for easy deployments of Backstage and its subsystems on
+  Kubernetes.
+
+- **[Backstage platform is stable](https://github.com/spotify/backstage/milestone/19)** -
+  The platform APIs and features are stable and can be depended on for
+  production use. After this plugins will require little to no maintenance.
+
 - **Backstage Design System** - By providing design guidelines for common plugin
   layouts together, rich set of reusable UI components
   ([Storybook](https://backstage.io/storybook)) and Figma design resources. The
   Design System will make it easy to design and build plugins that are
   consistent across the platform -- supporting both developers and designers.
 
-- **[TechDocs v1](https://github.com/spotify/backstage/milestone/16)** - Our
-  docs-like-code feature TechDocs working end to end.
-
-- **[Initial GraphQL API](https://github.com/spotify/backstage/milestone/13)** -
-  A GraphQL API will open up the rich metadata provided by Backstage in a single
-  query. Plugins can easily query this API as well as extend the model where
-  needed.
-
-- **Production deployments** - Provide instructions and default configurations
-  (e.g. through Helm charts) for easy deployments of Backstage and its
-  subsystems on Kubernetes.
-
-- **Cloud Cost Insights plugin (from Spotify)** - Spotify teams are fully
-  responsible for their own software, including the cost of the cloud resources
-  they use. By making our internal cost insights plugin available as open source
-  you will also be able to treat cost as an engineering problem, and make it
-  easy for your engineers to see their spend and where there's opportunity to
-  reduce waste.
-
 - Further improvements to platform documentation
 
 ### Plugins
@@ -96,10 +90,6 @@ Chances are that someone will jump in and help build it.
 
 ### Future work 🔮
 
-- **[Backstage platform is stable](https://github.com/spotify/backstage/milestone/19)** -
-  The platform APIs and features are stable and can be depended on for
-  production use. After this plugins will require little to no maintenance.
-
 - **Deploy a product demo at `demo.backstage.io`** - Deploy a typical Backstage
   deployment available publicly so that people can click around and get a feel
   for the product without having to install anything.
@@ -118,8 +108,16 @@ Chances are that someone will jump in and help build it.
   [AWS](https://github.com/spotify/backstage/issues/290),
   [Azure](https://github.com/spotify/backstage/issues/348) and others.
 
+- **[Initial GraphQL API](https://github.com/spotify/backstage/milestone/13)** -
+  A GraphQL API will open up the rich metadata provided by Backstage in a single
+  query. Plugins can easily query this API as well as extend the model where
+  needed.
+
 ### Completed milestones ✅
 
+- [Cost Insights plugin 💸](https://engineering.atspotify.com/2020/09/29/managing-clouds-from-the-ground-up-cost-engineering-at-spotify/)
+- [Donate Backstage to the CNCF 🎉](https://backstage.io/blog/2020/09/23/backstage-cncf-sandbox)
+- [TechDocs v1](https://backstage.io/blog/2020/09/08/announcing-tech-docs)
 - [Plugin marketplace](https://backstage.io/plugins)
 - [Improved and move documentation to backstage.io](https://backstage.io/docs/overview/what-is-backstage)
 - [Backstage Service Catalog (alpha)](https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha)

docs/overview/support.md

@@ -13,10 +13,7 @@ description: Support and Community Details and Links
 - [FAQ](../FAQ.md) - Frequently Asked Questions
 - [Code of Conduct](../../CODE_OF_CONDUCT.md) - This is how we roll
 - [Blog](https://backstage.io/blog/) - Announcements and updates
-- [Newsletter](https://mailchi.mp/spotify/backstage-community)
+- [Newsletter](https://mailchi.mp/spotify/backstage-community) - Subscribe to
+  our email newsletter
 - Give us a star ⭐️ - If you are using Backstage or think it is an interesting
   project, we would love a star ❤️
-
-Or, if you are an open source developer and are interested in joining our team,
-please reach out to
-[foss-opportunities@spotify.com ](mailto:foss-opportunities@spotify.com)

docs/overview/what-is-backstage.md

@@ -1,7 +1,7 @@
 ---
 id: what-is-backstage
 title: What is Backstage?
-description: Backsatge is an open platform for building developer portals.
+description: Backstage is an open platform for building developer portals.
 Powered by a centralized service catalog, Backstage restores order to your microservices and infrastructure
 ---
 
@@ -33,7 +33,14 @@ Out of the box, Backstage includes:
   [open source plugins](https://github.com/spotify/backstage/tree/master/plugins)
   that further expand Backstage’s customizability and functionality
 
-### Benefits
+## Backstage and the CNCF
+
+Backstage is a CNCF Sandbox project. Read the announcement
+[here](https://backstage.io/blog/2020/09/23/backstage-cncf-sandbox).
+
+<img src="https://backstage.io/img/cncf-white.svg" width="400" />
+
+## Benefits
 
 - For _engineering managers_, it allows you to maintain standards and best
   practices across the organization, and can help you manage your whole tech

docs/plugins/existing-plugins.md

@@ -4,12 +4,15 @@ title: Existing plugins
 description: Lists of existing open source plugins
 ---
 
-## Open source plugins
+## The Plugin Marketplace
 
-The full list of open source plugins can be found
-[here](https://github.com/spotify/backstage/tree/master/plugins).
+Open source plugins that you can add to your Backstage deployment can be found
+at:
 
-## Plugin gallery
+https://backstage.io/plugins
 
-TODO: In the future we would like to have something similar to
-https://grafana.com/grafana/plugins
+![](https://backstage.io/blog/assets/marketplace.png)
+
+## Links
+
+- [[blog] The Plugin Marketplace is open](https://backstage.io/blog/2020/09/30/plugin-marketplace)

docs/plugins/index.md

@@ -9,7 +9,7 @@ Backstage is a single-page application composed of a set of plugins.
 Our goal for the plugin ecosystem is that the definition of a plugin is flexible
 enough to allow you to expose pretty much any kind of infrastructure or software
 development tool as a plugin in Backstage. By following strong
-[design guidelines](../dls/design.md) we ensure the the overall user experience
+[design guidelines](../dls/design.md) we ensure the overall user experience
 stays consistent between plugins.
 
 ![plugin](../assets/my-plugin_screenshot.png)
@@ -21,7 +21,7 @@ To create a plugin, follow the steps outlined [here](create-a-plugin.md).
 ## Suggesting a plugin
 
 If you start developing a plugin that you aim to release as open source, we
-suggest that you create a new
+suggest that you create a
 [new Issue](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME).
 This helps the community know what plugins are in development.
 

docs/plugins/proxying.md

@@ -23,7 +23,7 @@ const proxyEnv = useHotMemoize(module, () => createEnv('proxy'));
 const service = createServiceBuilder(module)
   .loadConfig(configReader)
   /** ... other routers ... */
-  .addRouter('/proxy', await proxy(proxyEnv, '/proxy'));
+  .addRouter('/proxy', await proxy(proxyEnv));
 ```
 
 ## Configuration
@@ -49,7 +49,7 @@ Each key under the proxy configuration entry is a route to match, below the
 prefix that the proxy plugin is mounted on. It must start with a slash. For
 example, if the backend mounts the proxy plugin as `/proxy`, the above
 configuration will lead to the proxy acting on backend requests to
-`/proxy/simple-example/...` and `/proxy/larger-example/v1/...`.
+`/api/proxy/simple-example/...` and `/api/proxy/larger-example/v1/...`.
 
 The value inside each route is either a simple URL string, or an object on the
 format accepted by
@@ -74,6 +74,6 @@ except with the following caveats for convenience:
   commonly useful value.
 - If `pathRewrite` is not specified, it is set to a single rewrite that removes
   the entire prefix and route. In the above example, a rewrite of
-  `'^/proxy/larger-example/v1/': '/'` is added. That means that a request to
-  `/proxy/larger-example/v1/some/path` will be translated to a request to
+  `'^/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`.

docs/plugins/publishing.md

@@ -21,6 +21,9 @@ out a new branch that you will use for the release, e.g.
 $ git checkout -b new-release
 ```
 
+First bump the `CHANGELOG.md` in the root of the repo and commit. You bump it by
+adding a header for the new version just below the `## Next Release` one.
+
 Then, from the root of the repo, run
 
 ```sh

docs/plugins/structure-of-a-plugin.md

@@ -84,7 +84,7 @@ structure our plugins. There are usually one or multiple page components and
 next to them you can split up the UI in as many components as you feel like.
 
 We have the `ExamplePage` to show an example Backstage page component. The
-`ExampleFetchComponent` show cases the common task of making an async request to
+`ExampleFetchComponent` showcases the common task of making an async request to
 a public API and plot the response data in a table using Material-UI components.
 
 You may tweak these components, rename them and/or replace them completely.

docs/plugins/testing.md

@@ -32,7 +32,7 @@ working on.
 
 ## Naming Test Files
 
-Tests should be name `[filename].test.js`.
+Tests should be named `[filename].test.js`.
 
 For example, the tests for **`Link.js`** exist in the file **`Link.test.js`**.
 
@@ -54,7 +54,7 @@ TODO.
 
 # Writing Unit Tests
 
-The following principles are good guides to determining if you are writing high
+The following principles are good guides for determining if you are writing high
 quality frontend unit tests.
 
 ## Bad Unit Test Principle
@@ -166,11 +166,11 @@ because it fulfills all the principles above:
 ✓ **Fulfills Input/Output Principle**: Verifies the output changes when the
 input changes
 
-✓ **Fufills Blackbox Principle**: Does not verify _how_ the `<Loading />`
+✓ **Fulfills Blackbox Principle**: Does not verify _how_ the `<Loading />`
 component is mounted, just that it is mounted in response to the input.
 
 ✓ **Fulfills Scalability Principle**: If we decide to refactor the entire way
-the loading indicator is displayed the test still works without touching it.
+the loading indicator has displayed the test still works without touching it.
 
 ✓ **Fulfills Broken Functionality Principle**: this test verifies the
 functionality (displaying an indicator) is working, rather than how it is

docs/reference/utility-apis/AlertApi.md

@@ -73,7 +73,7 @@ Referenced by: [alert\$](#alert).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 

docs/reference/utility-apis/AppThemeApi.md

@@ -135,7 +135,7 @@ Referenced by: [activeThemeId\$](#activethemeid).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 

docs/reference/utility-apis/ErrorApi.md

@@ -93,7 +93,7 @@ Referenced by: [error\$](#error).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 

docs/reference/utility-apis/OAuthRequestApi.md

@@ -11,7 +11,8 @@ The following Utility API implements this type:
 ### createAuthRequester()
 
 A utility for showing login popups or similar things, and merging together
-multiple requests for different scopes into one request that inclues all scopes.
+multiple requests for different scopes into one request that includes all
+scopes.
 
 The passed in options provide information about the login provider, and how to
 handle auth requests.
@@ -30,7 +31,7 @@ createAuthRequester<AuthResponse>(
 
 ### authRequest\$()
 
-Observers panding auth requests. The returned observable will emit all current
+Observers pending auth requests. The returned observable will emit all current
 active auth request, at most one for each created auth requester.
 
 Each request has its own info about the login provider, forwarded from the auth
@@ -156,7 +157,7 @@ Referenced by: [authRequest\$](#authrequest).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 

docs/reference/utility-apis/SessionApi.md

@@ -81,7 +81,7 @@ Referenced by: [sessionState\$](#sessionstate).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 

docs/reference/utility-apis/SessionStateApi.md

@@ -62,7 +62,7 @@ Referenced by: [sessionState\$](#sessionstate).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 

docs/reference/utility-apis/StorageApi.md

@@ -35,7 +35,7 @@ remove(key: string): Promise<void>
 
 ### set()
 
-Save persistant data, and emit messages to anyone that is using observe\$ for
+Save persistent data, and emit messages to anyone that is using observe\$ for
 this key
 
 <pre>
@@ -85,7 +85,7 @@ Referenced by: [observe\$](#observe), [StorageApi](#storageapi).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 
@@ -129,7 +129,7 @@ export interface StorageApi {
   remove(key: string): Promise&lt;void&gt;;
 
   /**
-   * Save persistant data, and emit messages to anyone that is using observe$ for this key
+   * Save persistent data, and emit messages to anyone that is using observe$ for this key
    *
    * @param {String} key Unique key associated with the data.
    */

docs/tutorials/journey.md

@@ -134,7 +134,7 @@ work.
 # 5. The First User
 
 At this point the only things that anyone that wants to use Sam's plugin needs
-to do is to add
+to do are to add
 https://raw.githubusercontent.com/sam/backstage-spotify-theme/master/annotation.json#/sam.wise/spotify-track-id
 to their catalog schema, import and add the `PlayerWidget` on the desired entity
 template pages, and make sure they're providing Spotify auth.
@@ -145,7 +145,7 @@ select a theme tune when creating a new component. Sam jumps on the idea and
 adds a new creation hook that is exported by the plugin. The hook can be
 installed either in a single, all, or component templates that match a label. It
 adds a field as a part of the component creation process with a nice search box
-that allow users to search for a track that they want to use as the theme tune.
+that allows users to search for a track that they want to use as the theme tune.
 
 # 6. Return to the Repo
 
@@ -203,7 +203,7 @@ backend plugin also extends the common GraphQL schema with a mutation that
 updates the track ID in the database.
 
 On the frontend the Pull Request doesn't change much. It defines the save action
-the was previously using the `RepoApi` in it's own API.
+the was previously using the `RepoApi` in its own API.
 
 ```ts
 type ThemeTuneStorageApi = {
@@ -247,7 +247,7 @@ once an internal concern of the plugin is now becoming a standard in the
 community.
 
 In order to standardize the annotation in Backstage, Sam submits a Pull Request
-to the Backstage Core repo. The request suggest a new well-known metadata
+to the Backstage Core repo. The request suggests a new well-known metadata
 annotation called `spotify.com/track-id`, with the same schema definition as
 Sam's label, and refers to Sam's own plugin and the `spotify-album-art` plugin
 as existing usages. The Backstage maintainers merge the Pull Request, after

docs/tutorials/quickstart-app-auth.md

@@ -11,10 +11,11 @@ title: Monorepo App Setup With Authentication
 > own environment. It starts with a skeleton install and verifying of the
 > monorepo's functionality. Next, GitHub authentication is added and tested.
 >
-> This document assumes you have NodeJS 12 active along with Yarn. Please note,
-> that at the time of this writing, the current version is 0.1.1-alpha.21. This
-> guide can still be used with future versions, just, verify as you go. If you
-> run into issues, you can compare your setup with mine here >
+> This document assumes you have NodeJS 12 active along with Yarn and Python.
+> Please note, that at the time of this writing, the current version is
+> 0.1.1-alpha.21. This guide can still be used with future versions, just,
+> verify as you go. If you run into issues, you can compare your setup with mine
+> here >
 > [simple-backstage-app](https://github.com/johnson-jesse/simple-backstage-app).
 
 # The Skeleton Application
@@ -115,7 +116,7 @@ export AUTH_GITHUB_CLIENT_SECRET=xxx
 > Log into http://github.com
 > Navigate to (Settings > Developer Settings > OAuth Apps > New OAuth App)[https://github.com/settings/applications/new]
 > Set Homepage URL = http://localhost:3000
-> Set Callback URL = http://localhost:7000/auth/github
+> Set Callback URL = http://localhost:7000/api/auth/github
 > Click [Register application]
 > On the next page, copy and paste your new Client ID and Client Secret to the environment variables above, `AUTH_GITHUB_CLIENT_ID` & `AUTH_GITHUB_CLIENT_SECRET`
 > Don't forget to `source` that profile file again if necessary.
@@ -155,39 +156,7 @@ const app = createApp({
 });
 ```
 
-6. Open and change _root > packages > app > src >_ `apis.ts` as follows
-
-```ts
-// Add the following imports to the existing list from core
-import { githubAuthApiRef, GithubAuth } from '@backstage/core';
-```
-
-7. In the same file, change the builder block for oauthRequestApiRef as follows
-
-_from:_
-
-```ts
-builder.add(oauthRequestApiRef, new OAuthRequestManager());
-```
-
-_to:_
-
-```ts
-const oauthRequestApi = builder.add(
-  oauthRequestApiRef,
-  new OAuthRequestManager(),
-);
-
-builder.add(
-  githubAuthApiRef,
-  GithubAuth.create({
-    discoveryApi,
-    oauthRequestApi,
-  }),
-);
-```
-
-8. Start the backend and frontend as before
+7. Start the backend and frontend as before
 
 When the browser loads, you should be presented with a login page for GitHub.
 Login as usual with your GitHub account. If this is your first time, you will be

docs/tutorials/quickstart-app-plugin.md

@@ -20,10 +20,11 @@ title: Adding Custom Plugin to Existing Monorepo App
 > functionality, extend the Sidebar to make our life easy. Finally, we add
 > custom code to display GitHub repository information.
 >
-> This document assumes you have NodeJS 12 active along with Yarn. Please note,
-> that at the time of this writing, the current version is 0.1.1-alpha.21. This
-> guide can still be used with future versions, just, verify as you go. If you
-> run into issues, you can compare your setup with mine here >
+> This document assumes you have NodeJS 12 active along with Yarn and Python.
+> Please note, that at the time of this writing, the current version is
+> 0.1.1-alpha.21. This guide can still be used with future versions, just,
+> verify as you go. If you run into issues, you can compare your setup with mine
+> here >
 > [simple-backstage-app-plugin](https://github.com/johnson-jesse/simple-backstage-app-plugin).
 
 # The Skeleton Plugin
@@ -210,7 +211,7 @@ type Viewer = {
 };
 ```
 
-# The Tabel Model
+# The Table Model
 
 Using Backstage's own component library, let's define a custom table. This
 component will get used if we have data to display.
@@ -312,6 +313,6 @@ return (
 > Break apart ExampleFetchComponent into smaller logical parts contained in
 > their own files. Rename your components to something other than ExampleXxx.
 >
-> You might be real proud of a plugin you develop. Follow this next tutorial for
-> an in-depth look at publishing and including that for the entire Backstage
+> You might be really proud of a plugin you develop. Follow this next tutorial
+> for an in-depth look at publishing and including that for the entire Backstage
 > community. [TODO](#).

microsite/.prettierignore

@@ -0,0 +1 @@
+build

microsite/blog/2020-09-30-backstage-design-system.md

@@ -0,0 +1,107 @@
+---
+title: How to design for Backstage (even if you’re not a designer)
+author: Kat Zhou
+authorURL: http://twitter.com/katherinemzhou
+---
+
+![img](assets/backstage-DS-header.png)
+
+We are excited to launch the Backstage Design System, which includes a [Figma UI kit](https://www.figma.com/community/file/850673348101741100), a rich set of [reusable code components](http://backstage.io/storybook) on Storybook, and [Guidelines](https://backstage.io/docs/dls/design) for designers and developers as they build plugins for Backstage.
+
+<!--truncate-->
+
+## Not just the way it looks
+
+We see great design as one of the secret weapons of Backstage. Design should never be an afterthought — we believe an elegant, cohesive UX is vital to what makes Backstage such a productive, end-to-end development environment.
+
+Backstage keeps engineers from getting lost inside the complexity of your infrastructure by bringing order to your software ecosystem (through the [service catalog](https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha)) and providing an abstraction layer on top of it. How that abstraction layer works is essential to how Backstage works. So we’ve spent time figuring out how to make great design in Backstage easier to achieve for both designers and non-designers alike.
+
+Since making Backstage open source, we’ve been able to host design studios and user interviews with teams outside Spotify to get feedback and collaborate on a design system, together. (And we’re always keen on collaborating with more organizations.)
+
+![img](assets/Backstage-mural-DS.png)
+_Screenshot of our design studio for Backstage Search, which included stakeholders inside and outside of Spotify._
+
+As Backstage has gained traction, we’ve seen the importance of creating a scalable and coherent design system. It’s through the shared guidelines of our design system that we are able to maintain a unified ecosystem of plugins for our users, globally. Let’s get started by taking a closer look at the different design components of a plugin.
+
+## Anatomy of a plugin
+
+![](https://backstage.io/img/cards-plugins.png)
+
+Plugins are what provide the feature functionality in Backstage, allowing you to customize it to fit your infrastructure. They are integrated into Backstage's frontend, so that no matter what tool or service is being accessed, users are guaranteed a seamless experience.
+
+As you begin to [build your own plugins](https://backstage.io/docs/plugins/), we encourage you to explore the [open source plugins](https://backstage.io/plugins) we have available in Backstage, as reference. The anatomy of a plugin is simple. In the example below, we’ve highlighted a few of the standard components you should consider when designing your plugin.
+
+![img](assets/backstage-guide-DS.png)
+
+1. **Tabs.** Want to include multiple pages in your plugin? Use our tab component so users can easily navigate through your plugin.
+2. **Title.** Plugin pages should always have a title. Subheads are optional. Typically, the ‘star’ icon is included in the overview tab, which allows the user to favorite the plugin, adding it to the side navigation.
+3. **Cards.** Use the card components to display different kinds of content and functionality. You can follow our 12-column, responsive grid system to arrange the cards.
+4. **Support.** There should always be a support button (tertiary style, with icon). There can also be a primary action button as well as a secondary one.
+5. **Header.** Use the Backstage header to allow for users to easily understand what they’re looking at. You can include an optional subhead as well as other information. The color varies depending on the type of plugin you’ve built (stand-alone tool, service, app, website, etc.).
+
+Now that we’ve familiarized ourselves with the basic parts of a plugin, let’s take a look at some of the tools and resources that make designing plugins even easier.
+
+## Tools and resources
+
+The quickest way to start is by duplicating our [Figma UI kit](https://www.figma.com/community/file/850673348101741100), then clicking on the Create a Plugin page on the left-hand side to grab some templates. Feel free to experiment and play around! Figma is a fantastic, multiplayer tool that allows for designers and developers to co-create components and share specs with ease. We’re excited to see what you design and develop.
+
+As you’re designing and building your plugins, make sure to take advantage of these helpful resources.
+
+![img](assets/backstage-figma1-DS.png)
+![img](assets/backstage-figma2-ds.png)
+
+### [Figma Community](https://www.figma.com/@backstage)
+
+We are thrilled to be using [Figma Community](https://www.figma.com/@backstage) to share our design assets. You can duplicate our UI kit and design your own plugin for Backstage. Figma Community is currently in beta, so this is a neat opportunity to be testing out a new way of working. At the moment, it doesn’t support auto-updating of duplicated files, so we’ll be announcing new versions of our UI kit on Discord in the #design channel.
+
+![img](assets/backstage-storybook-ds.png)
+
+### [Storybook](https://backstage.io/storybook/)
+
+You can view (and grab) our [reusable components on Storybook](https://backstage.io/storybook/). If you’d like to help build up our design system, you can also help us add components that we’ve designed to Storybook as well. We post newly designed components and patterns to GitHub as issues, where contributors can pick them up and add them to our Storybook so they’re available for the rest of the Backstage community.
+
+![img](assets/backstage-guidelines-ds.png)
+
+### [Guidelines](https://backstage.io/docs/dls/design)
+
+To keep up with our latest design guidelines, go to [Designing for Backstage](https://backstage.io/docs/dls/design). You’ll find more how-to’s and you can also learn more about our design philosophy and practices there. Down the line, we plan on including more in-depth component rules in this section (i.e., dos/don’ts, use cases, etc.).
+
+![img](assets/backstage-github-ds.png)
+
+### [GitHub](https://github.com/spotify/backstage)
+
+Join in on the action [at spotify/backstage on GitHub](https://github.com/spotify/backstage) by submitting issues and opening pull requests for all things related to components and patterns in Backstage.
+
+![img](assets/backstage-discord-DS.png)
+
+### [Discord](https://discord.com/invite/MUpMjP2)
+
+All design questions should be directed to the [#design](https://discord.com/channels/687207715902193673/696709358544879716) channel in [Discord](https://discord.com/invite/MUpMjP2).
+
+## What's next for Backstage design
+
+There are a lot of exciting things that we’re envisioning for Backstage and open source design at Spotify. These include:
+
+- Expanding our Backstage Design System by building on the UI kit and component library in Figma and Storybook
+
+* Collaborating with more of our amazing contributors to ensure our Backstage Design System works for everyone
+
+* Featuring rad plugins that folks have created, using our design system, in our Figma Community space
+
+* Building up our Guidelines by continuing to creating robust design documentation
+
+* Ensuring that we maintain accessible practices throughout our experience
+
+![img](assets/backstage-world-DS.png)
+
+## Get involved
+
+Designing in the open needs to be democratic and participatory, which is why we invite you to join in on the fun! There are a couple things you can do to get involved, such as:
+
+- **Build with us!** Are there components/plugins that you’d like to see in Backstage? Feel free to create an example/prototype of what you’re envisioning and create a UX component issue in our GitHub repo.
+
+- **Chat with us!** If you have questions, ideas, or puppy GIFs, feel free to reach out to us on Discord in the #design channel.
+
+- **Share with us!** One of our priorities is making Backstage more accessible, and we need your help. If you’ve got A11Y insights and ideas on how we can improve our product, please let us know!
+
+- **Work with us!** We are hiring for product designers to work on Backstage. We strongly stand for breaking traditional pipelines and elevating our caliber by hiring the best folks who are underrepresented minorities in tech today. Keen on joining? Know someone who has a knack for open source design and design systems? Send a direct message to @katz on Discord!

microsite/blog/2020-09-30-plugin-marketplace.md

@@ -0,0 +1,43 @@
+---
+title: The Plugin Marketplace is open
+author: Stefan Ålund
+authorURL: https://twitter.com/stalund
+---
+
+Backstage has an ambitious goal: to provide engineers with the best possible developer experience.
+
+A great developer experience leads to happy, creative, and productive engineers. Our belief is that engineers should not have to be experts in various infrastructure tools or disciplines (e.g., machine learning or backend) to be productive. Infrastructure should be abstracted away, so that developers can spend more cycles building and testing, quickly and safely. Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.
+
+Now you may be thinking, “Yeah, sure, that sounds nice and all, but how does Backstage actually abstract away infrastructure?” The short answer: [plugins](https://backstage.io/plugins).
+
+![plugins](https://backstage.io/img/cards-plugins.png)
+
+<!--truncate-->
+
+Think of plugins as a mini version of an infrastructure tool or service — just the parts you need, made quick and easy. The advantage of using a Backstage plugin instead of a tool’s dedicated UI is that all your infrastructure is packaged into a “single pane of glass” instead of being spread out like independently built “islands”. Once you grow your infrastructure portfolio, the complexity really starts to add up. The Backstage plugin model allows you to add more tools without increasing the cognitive load for your users.
+
+Our goal for the plugin ecosystem is that anything can be a plugin. The definition of a plugin is flexible enough to allow you to expose pretty much any kind of infrastructure or software development tool as a plugin in Backstage. By following clear [design guidelines](https://backstage.io/blog/2020/09/30/backstage-design-system) we ensure the overall user experience stays consistent between plugins. If we all do our job well, the end user of Backstage does not see the boundaries between plugins. They are interacting with one consistent product — with many features.
+
+## Building an ecosystem
+
+Imagine a not-so-distant future where you walk up to Backstage, install it in your environment, and then choose from a gallery of existing, open source plugins that serve and match whatever infrastructure and software development needs you have inside your company. That means you can get started with Backstage and see the gains of improved productivity within days, not months. That is our vision for the Backstage plugin ecosystem.
+
+Running services on Kubernetes? There’s a plugin for that. Using Snyk for security scanning? There’s a plugin for that. Grafana, DataDog, or Rollbar for monitoring? There’s a plugin for that. Using Jenkins, CircleCI, GitHub Actions, or Travis CI? Pick the CI plugin of your choice. You get the picture. Regardless of your stack, there’s a plugin that you can use.
+
+Like this vision? So do we! But we can’t do it alone. We’ll need your help. For this vision to come true, we need to foster a community where many companies and individual developers build and contribute their plugins. Having been [accepted into the CNCF Sandbox](https://backstage.io/blog/2020/09/23/backstage-cncf-sandbox) provides us with the groundwork and guidance to broaden the community even faster.
+
+This grand vision is actually not that far off. Already today there is a growing ecosystem of Backstage plugins. To highlight all the amazing work that has been done by the community, and make it easier for Backstage adopters to see what plugins are available, we now have a Plugin Marketplace: [https://backstage.io/plugins](https://backstage.io/plugins)
+
+![marketplace](assets/marketplace.png)
+
+## Creating and suggesting new plugins
+
+Not all plugins you need will be open source. Every company has their own homegrown tooling. Building internal plugins lets you tailor your version of Backstage to be a perfect fit for your infrastructure and software development needs. If you end up [building plugins](https://backstage.io/docs/plugins/create-a-plugin) that could be useful for other companies, please consider releasing them as open source and [add them to the Marketplace](https://backstage.io/docs/plugins/add-to-marketplace).
+
+If you start developing a plugin that you aim to release as open source, we suggest that you create a [new plugin Issue](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). This helps the community know what plugins are in development and opens up opportunities for collaboration. You can also use this process if you have an idea for a good plugin, but you need help building it.
+
+We are really excited to see all the amazing plugins that have already been built, and look forward to seeing even more ideas and collaboration as the Backstage community continues to grow.
+
+What plugins would you like to see in the Plugin Marketplace? [Tell us](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME)!
+
+_Special shout-out to community member [Iain Billett](https://github.com/iain-b) from Roadie for helping build and contribute the [Plugin Marketplace page](https://backstage.io/plugins) (as his first PR no less!)._

microsite/core/Footer.js

@@ -51,6 +51,7 @@ class Footer extends React.Component {
             <a href="https://mailchi.mp/spotify/backstage-community">
               Subscribe to our newsletter
             </a>
+            <a href="https://www.cncf.io/sandbox-projects/">CNCF Sandbox</a>
           </div>
           <div>
             <h5>More</h5>

microsite/data/plugins/cloud-build.yaml

@@ -0,0 +1,13 @@
+---
+title: Google Cloud Build
+author: Trivago
+authorUrl: https://www.trivago.com
+category: CI
+description: Build, test, and deploy on Google's serverless CI/CD platform.
+documentation: https://github.com/spotify/backstage/tree/master/plugins/cloudbuild
+iconUrl: https://avatars2.githubusercontent.com/u/38220399?s=400&v=4
+npmPackageName: '@backstage/plugin-cloudbuild'
+tags:
+  - ci
+  - cd
+  - test