From c2386e9e860325f43775d700a016b91ecd7053d0 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@hallila.com>
Date: Mon, 11 Jan 2021 08:57:15 +0100
Subject: [PATCH 01/50] Modifying auth tutorial to contain different providers.
 Adding a better example repo link.

---
 docs/tutorials/quickstart-app-auth.md | 265 +++++++++++++++++++++++---
 1 file changed, 239 insertions(+), 26 deletions(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 1dcca9d7e0..ecafd47b8c 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -3,20 +3,17 @@ id: quickstart-app-auth
 title: Monorepo App Setup With Authentication
 ---
 
-###### September 15th 2020 - @backstage/create-app - v0.1.1-alpha.21
+###### January 8th 2021 - @backstage/create-app - v0.4.5
 
 <br />
 
 > This document takes you through setting up a Backstage app that runs in your
 > own environment. It starts with a skeleton install and verifying of the
-> monorepo's functionality. Next, GitHub authentication is added and tested.
+> monorepo's functionality. Next, authentication is added and tested.
 >
 > This document assumes you have Node.js 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).
+> Please note, that at the time of this writing, the current version is v0.4.5
+> This guide can still be used with future versions, just, verify as you go.
 
 # The Skeleton Application
 
@@ -55,6 +52,16 @@ guest. Let's fix that now and add auth.
 
 # The Auth Configuration
 
+Default Backstage installation includes multiple authentication providers out of
+the box. The steps to enable new authentication provider in Backstage are very
+similar to each other, the biggest difference is usually configuring the
+external authentication provider. Please see a subset of possible providers and
+instructions to integrate them below. Steps 1 & 2 are described separately for
+each provider and steps beyond that are common for all.
+
+<details><summary>Github</summary>
+<p>
+
 1. Open `app-config.yaml` and change it as follows
 
 _from:_
@@ -75,23 +82,224 @@ auth:
           $env: AUTH_GITHUB_CLIENT_ID
         clientSecret:
           $env: AUTH_GITHUB_CLIENT_SECRET
-        ## uncomment the following three lines if using enterprise
+        ## uncomment the following two lines if using enterprise
         # enterpriseInstanceUrl:
         #  $env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL
 ```
 
-2. Set environment variables in whatever fashion is easiest for you. I chose to
+2. Generate Github client id and secret
+
+- 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/api/auth/github
+- Click [Register application]
+- On the next page, copy and paste your new Client ID and Client Secret to
+  environment variables defined in the `app-config.yaml` file,
+  `AUTH_GITHUB_CLIENT_ID` & `AUTH_GITHUB_CLIENT_SECRET`
+
+</p>
+</details>
+
+<details><summary>Gitlab</summary>
+<p>
+
+1. Open `app-config.yaml` and change it as follows
+
+_from:_
+
+```yaml
+auth:
+  providers: {}
+```
+
+_to:_
+
+```yaml
+auth:
+  providers:
+    gitlab:
+      development:
+        clientId:
+          $env: AUTH_GITLAB_CLIENT_ID
+        clientSecret:
+          $env: AUTH_GITLAB_CLIENT_SECRET
+        audience: https://gitlab.com # Or your self-hosted Gitlab instance URL
+```
+
+2. Generate Gitlab Application for client id and secret
+
+- Log into Gitlab
+- Navigate to (Profile > Settings >
+  Applications)[https://gitlab.com/-/profile/applications]
+- Name your application
+- Set Callback URL = http://localhost:7000/api/auth/gitlab/handler/frame
+- Select the following values:
+  - `read_user (Read the authenticated user's personal information)`
+  - `read_repository (Allows read-only access to the repository)`
+  - `write_repository (Allows read-write access to the repository)`
+  - `openid (Authenticate using OpenID Connect)`
+  - `profile (Allows read-only access to the user's personal information using OpenID Connect)`
+  - `email (Allows read-only access to the user's primary email address using OpenID Connect)`
+- Click [Save application]
+- On the next page, copy and paste your new Application ID and Secret to
+  environment variables defined in the `app-config.yaml` file,
+  `AUTH_GITLAB_CLIENT_ID` & `AUTH_GITLAB_CLIENT_SECRET`
+
+</p>
+</details>
+
+<details><summary>Google</summary>
+<p>
+
+1. Open `app-config.yaml` and change it as follows
+
+_from:_
+
+```yaml
+auth:
+  providers: {}
+```
+
+_to:_
+
+```yaml
+auth:
+  providers:
+    google:
+      development:
+        clientId:
+          $env: AUTH_GOOGLE_CLIENT_ID
+        clientSecret:
+          $env: AUTH_GOOGLE_CLIENT_SECRET
+```
+
+2. Generate Google Application in Google Cloud console
+
+- Log into https://console.cloud.google.com
+- Select or create a new project from the dropdown on the top bar
+- Navigate to (APIs & Services - >
+  Credentials)[https://console.cloud.google.com/apis/credentials]
+- Add new Authorised JavaScript origin = `http://localhost:3000`
+- Add new Authorised redirect URI =
+  `http://localhost:7000/api/auth/google/handler/frame`
+- Click [Save application]
+- Google should display a modal with your Client ID and Secret. Copy and paste
+  those to environment variables defined in the `app-config.yaml` file,
+  `AUTH_GOOGLE_CLIENT_ID` & `AUTH_GOOGLE_CLIENT_SECRET`
+
+</p>
+</details>
+
+<details><summary>Microsoft</summary>
+<p>
+
+1. Open `app-config.yaml` and change it as follows
+
+_from:_
+
+```yaml
+auth:
+  providers: {}
+```
+
+_to:_
+
+```yaml
+auth:
+  providers:
+    microsoft:
+      development:
+        clientId:
+          $env: AUTH_MICROSOFT_CLIENT_ID
+        clientSecret:
+          $env: AUTH_MICROSOFT_CLIENT_SECRET
+        tenantId:
+          $env: AUTH_MICROSOFT_TENANT_ID
+```
+
+2. Create Microsoft Directory in Microsoft Portal
+
+- Log into https://portal.azure.com
+- Navigate to (Azure Active Directory -> App
+  Registrations)[https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps]
+- Create a New Registration
+- Add new Redirect URI = `http://localhost:3000`
+- Add new Authorised redirect URI =
+  `http://localhost:7000/api/auth/microsoft/handler/frame`
+- Click [Save application]
+- Set environment variable `AUTH_MICROSOFT_CLIENT_ID` from
+  `Application (client) Id` displayed on the directory page
+- Set environment variable `AUTH_MICROSOFT_TENANT_ID` from
+  `Directory (tenant) ID` displayed on the directory page
+- Navigate to Certificates & Secrets section and click [Create a new secret]
+- Set environment variable `AUTH_MICROSOFT_CLIENT_SECRET` from the `value` field
+  created.
+
+</p>
+</details>
+
+<details><summary>Auth0</summary>
+<p>
+
+1. Open `app-config.yaml` and change it as follows
+
+_from:_
+
+```yaml
+auth:
+  providers: {}
+```
+
+_to:_
+
+```yaml
+auth:
+  providers:
+    auth0:
+      development:
+        clientId:
+          $env: AUTH_AUTH0_CLIENT_ID
+        clientSecret:
+          $env: AUTH_AUTH0_CLIENT_SECRET
+        domain:
+          $env: AUTH_AUTH0_DOMAIN_ID
+```
+
+2. Create Auth0 application in Auth0 management console
+
+- Log into https://manage.auth0.com/dashboard/
+- Navigate to Applications
+- Create a New Application
+  - Select Single Page Web Application
+- Go to Settings tab
+- Add new line to Allowed Callback URLs =
+  `http://localhost:7000/api/auth/auth0/handler/frame`
+- Click [Save Changes]
+- Set environment variables displayed on the Basic Information page
+  - `AUTH_AUTH0_CLIENT_ID` from `Client ID` displayed on Auth0 application page
+  - `AUTH_AUTH0_CLIENT_SECRET` from `Client Secret` displayed on Auth0
+    application page
+  - `AUTH_AUTH0_DOMAIN_ID` from `Domain` displayed on Auth0 application page
+
+</p>
+</details>
+
+3. Set environment variables in whatever fashion is easiest for you. I chose to
    add mine to my `.zshrc` profile.
 
 ```zsh
 # For macOS Catalina & Z Shell
 # ------ simple-backstage-app GitHub
+#
+# (Change the name of the environment variables based on your auth setup above
 export AUTH_GITHUB_CLIENT_ID=xxx
 export AUTH_GITHUB_CLIENT_SECRET=xxx
 # export AUTH_GITHUB_ENTERPRISE_INSTANCE_URL=https://github.{MY_BIZ}.com
 ```
 
-3. And of course I need to source that file.
+4. And of course I need to source that file.
 
 ```zsh
 # Loading the new variables
@@ -107,26 +315,26 @@ export AUTH_GITHUB_CLIENT_SECRET=xxx
 > ...
 ```
 
-4. The values to replace `xxx` above come from your oauth app setup.
-
-```
-> 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/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.
-```
-
-5. Open and change _root > packages > app > src >_`App.tsx` as follows
+6. Open and change _root > packages > app > src >_`App.tsx` to use correct
+   authentication provider reference
 
 ```tsx
-// Add the following imports to the existing list from core
 import { githubAuthApiRef, SignInPage } from '@backstage/core';
 ```
 
-6. In the same file, change the createApp function as follows
+Modify the imported reference based on authentication method selected above
+
+| Auth Provider | Import Name         |
+| ------------- | ------------------- |
+| Github        | githubAuthApiRef    |
+| Gitlab        | gitlabAuthApiRef    |
+| Google        | googleAuthApiRef    |
+| Microsoft     | microsoftAuthApiRef |
+| Auth0         | googleAuthApiRef    |
+
+7. In the same file, modify createApp
+
+Remeber to modify the provider information based on the table above.
 
 ```tsx
 const app = createApp({
@@ -153,12 +361,17 @@ const app = createApp({
 });
 ```
 
-7. Start the backend and frontend as before
+After finishing setting up one (or multiple) authentication providers defined
+above you can 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
 asked to authorize and then are redirected to the catalog page if all is well.
 
+For more information you can clone the repository:
+https://github.com/RoadieHQ/backstage-auth-example Each authentication setting
+is set up there on a branch named after the authentication provider.
+
 # Where to go from here
 
 > You're probably eager to write your first custom plugin. Follow this next

From e9c75d64a3aff49109d8f5851d17c0f7d02455df Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@hallila.com>
Date: Mon, 11 Jan 2021 09:02:26 +0100
Subject: [PATCH 02/50] Fix typos.

---
 docs/tutorials/quickstart-app-auth.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index ecafd47b8c..5991f626e7 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -293,7 +293,7 @@ auth:
 # For macOS Catalina & Z Shell
 # ------ simple-backstage-app GitHub
 #
-# (Change the name of the environment variables based on your auth setup above
+# (Change the name of the environment variables based on your auth setup above)
 export AUTH_GITHUB_CLIENT_ID=xxx
 export AUTH_GITHUB_CLIENT_SECRET=xxx
 # export AUTH_GITHUB_ENTERPRISE_INSTANCE_URL=https://github.{MY_BIZ}.com
@@ -315,7 +315,7 @@ export AUTH_GITHUB_CLIENT_SECRET=xxx
 > ...
 ```
 
-6. Open and change _root > packages > app > src >_`App.tsx` to use correct
+5. Open and change _root > packages > app > src >`App.tsx` to use correct
    authentication provider reference
 
 ```tsx
@@ -332,9 +332,9 @@ Modify the imported reference based on authentication method selected above
 | Microsoft     | microsoftAuthApiRef |
 | Auth0         | googleAuthApiRef    |
 
-7. In the same file, modify createApp
+6. In the same file, modify createApp
 
-Remeber to modify the provider information based on the table above.
+Remember to modify the provider information based on the table above.
 
 ```tsx
 const app = createApp({

From b62bc928de9693d2af8e7cd131018f6d522021ed Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@hallila.com>
Date: Mon, 11 Jan 2021 09:41:06 +0100
Subject: [PATCH 03/50] Run prettier.

---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 5991f626e7..b6370fd1f9 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -315,7 +315,7 @@ export AUTH_GITHUB_CLIENT_SECRET=xxx
 > ...
 ```
 
-5. Open and change _root > packages > app > src >`App.tsx` to use correct
+5. Open and change \_root > packages > app > src >`App.tsx` to use correct
    authentication provider reference
 
 ```tsx

From 34206f81f05459a675c40e0351cdd0b0de8b97ed Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@hallila.com>
Date: Mon, 11 Jan 2021 13:47:47 +0100
Subject: [PATCH 04/50] Adding reference to latest node LTS as well.

Resolves:
* https://github.com/backstage/backstage/pull/4003#discussion_r554920635
---
 docs/tutorials/quickstart-app-auth.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index b6370fd1f9..48b5d2b3a7 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -11,9 +11,10 @@ title: Monorepo App Setup With Authentication
 > own environment. It starts with a skeleton install and verifying of the
 > monorepo's functionality. Next, authentication is added and tested.
 >
-> This document assumes you have Node.js 12 active along with Yarn and Python.
-> Please note, that at the time of this writing, the current version is v0.4.5
-> This guide can still be used with future versions, just, verify as you go.
+> This document assumes you have Node.js 12 or 14 active along with Yarn and
+> Python. Please note, that at the time of this writing, the current version is
+> v0.4.5 This guide can still be used with future versions, just, verify as you
+> go.
 
 # The Skeleton Application
 

From 82e35cd6531b9b62d4b264dd831a5585fc2e24b0 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Mon, 11 Jan 2021 16:57:58 +0100
Subject: [PATCH 05/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 48b5d2b3a7..88ccce6ae5 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -13,7 +13,7 @@ title: Monorepo App Setup With Authentication
 >
 > This document assumes you have Node.js 12 or 14 active along with Yarn and
 > Python. Please note, that at the time of this writing, the current version is
-> v0.4.5 This guide can still be used with future versions, just, verify as you
+> v0.4.5. This guide can still be used with future versions, just, verify as you
 > go.
 
 # The Skeleton Application

From ff4e53bd4ebb257732b0374cc6b2d19988e1cfe7 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Mon, 11 Jan 2021 16:58:08 +0100
Subject: [PATCH 06/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 88ccce6ae5..2affcec7fc 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -53,7 +53,7 @@ guest. Let's fix that now and add auth.
 
 # The Auth Configuration
 
-Default Backstage installation includes multiple authentication providers out of
+A default Backstage installation includes multiple authentication providers out of
 the box. The steps to enable new authentication provider in Backstage are very
 similar to each other, the biggest difference is usually configuring the
 external authentication provider. Please see a subset of possible providers and

From 322b04bff7191e0f31591a9306888e140b48f7fb Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Mon, 11 Jan 2021 16:58:14 +0100
Subject: [PATCH 07/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 2affcec7fc..12d3767791 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -54,7 +54,7 @@ guest. Let's fix that now and add auth.
 # The Auth Configuration
 
 A default Backstage installation includes multiple authentication providers out of
-the box. The steps to enable new authentication provider in Backstage are very
+the box. The steps to enable new authentication providers in Backstage are very
 similar to each other, the biggest difference is usually configuring the
 external authentication provider. Please see a subset of possible providers and
 instructions to integrate them below. Steps 1 & 2 are described separately for

From f3165cce9535a17d7698a584c90397d8ba351dfe Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Mon, 11 Jan 2021 16:58:24 +0100
Subject: [PATCH 08/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 12d3767791..7e05a5a63d 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -88,7 +88,7 @@ auth:
         #  $env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL
 ```
 
-2. Generate Github client id and secret
+2. Generate a GitHub client ID and secret
 
 - Log into http://github.com
 - Navigate to (Settings > Developer Settings > OAuth Apps > New OAuth

From 642bf0be1a47df153704e32e8304fe98ef94ce65 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Mon, 11 Jan 2021 16:59:17 +0100
Subject: [PATCH 09/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 7e05a5a63d..0f5e452aa5 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -103,7 +103,7 @@ auth:
 </p>
 </details>
 
-<details><summary>Gitlab</summary>
+<details><summary>GitLab</summary>
 <p>
 
 1. Open `app-config.yaml` and change it as follows

From 72399d57e5612b6198bce30efd2910ab67effef4 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Mon, 11 Jan 2021 16:59:38 +0100
Subject: [PATCH 10/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 0f5e452aa5..2d23402edd 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -129,7 +129,7 @@ auth:
         audience: https://gitlab.com # Or your self-hosted Gitlab instance URL
 ```
 
-2. Generate Gitlab Application for client id and secret
+2. Generate a GitLab Application client ID and secret
 
 - Log into Gitlab
 - Navigate to (Profile > Settings >

From cc64069374adea4d24e4781f2ca64cb4fb8d0da5 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Mon, 11 Jan 2021 16:59:51 +0100
Subject: [PATCH 11/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 2d23402edd..b58596b434 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -131,7 +131,7 @@ auth:
 
 2. Generate a GitLab Application client ID and secret
 
-- Log into Gitlab
+- Log into GitLab
 - Navigate to (Profile > Settings >
   Applications)[https://gitlab.com/-/profile/applications]
 - Name your application

From 163e263d8eb8e06868f7d464ba86b3adfaf76a23 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Mon, 11 Jan 2021 17:00:35 +0100
Subject: [PATCH 12/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index b58596b434..00c97cfe4b 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -180,7 +180,7 @@ auth:
 
 - Log into https://console.cloud.google.com
 - Select or create a new project from the dropdown on the top bar
-- Navigate to (APIs & Services - >
+- Navigate to (APIs & Services >
   Credentials)[https://console.cloud.google.com/apis/credentials]
 - Add new Authorised JavaScript origin = `http://localhost:3000`
 - Add new Authorised redirect URI =

From ecba810c98a37c72a915061f5822eec338db62a2 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Mon, 11 Jan 2021 17:01:32 +0100
Subject: [PATCH 13/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 00c97cfe4b..1cae03469d 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -323,7 +323,7 @@ export AUTH_GITHUB_CLIENT_SECRET=xxx
 import { githubAuthApiRef, SignInPage } from '@backstage/core';
 ```
 
-Modify the imported reference based on authentication method selected above
+Modify the imported reference based on the authentication method you selected above:
 
 | Auth Provider | Import Name         |
 | ------------- | ------------------- |

From 33267d1cb9f398153634a2dfb0851b5edfc488c8 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Mon, 11 Jan 2021 17:01:39 +0100
Subject: [PATCH 14/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 1cae03469d..900c52c484 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -331,7 +331,7 @@ Modify the imported reference based on the authentication method you selected ab
 | Gitlab        | gitlabAuthApiRef    |
 | Google        | googleAuthApiRef    |
 | Microsoft     | microsoftAuthApiRef |
-| Auth0         | googleAuthApiRef    |
+| Auth0         | auth0AuthApiRef    |
 
 6. In the same file, modify createApp
 

From 39b45b62b4889953dcf8676cf61b75d5f3a51876 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Mon, 11 Jan 2021 17:01:49 +0100
Subject: [PATCH 15/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 900c52c484..db97ae5ed4 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -369,8 +369,8 @@ 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
 asked to authorize and then are redirected to the catalog page if all is well.
 
-For more information you can clone the repository:
-https://github.com/RoadieHQ/backstage-auth-example Each authentication setting
+For more information you can clone [the backstage-auth-example repository](https://github.com/RoadieHQ/backstage-auth-example).
+ Each authentication setting
 is set up there on a branch named after the authentication provider.
 
 # Where to go from here

From dc48cfc9f2d862f8ec805ffc4fc67d0ae33b0e27 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Tue, 12 Jan 2021 08:27:31 +0100
Subject: [PATCH 16/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index db97ae5ed4..364e4a434a 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -268,7 +268,7 @@ auth:
           $env: AUTH_AUTH0_DOMAIN_ID
 ```
 
-2. Create Auth0 application in Auth0 management console
+2. Create an Auth0 application in the Auth0 management console
 
 - Log into https://manage.auth0.com/dashboard/
 - Navigate to Applications

From 4f0993407b406037d0468a77638d82da6993ed51 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Tue, 12 Jan 2021 08:31:32 +0100
Subject: [PATCH 17/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 364e4a434a..0fd48dc7bf 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -223,7 +223,7 @@ auth:
 2. Create Microsoft Directory in Microsoft Portal
 
 - Log into https://portal.azure.com
-- Navigate to (Azure Active Directory -> App
+- Navigate to (Azure Active Directory > App
   Registrations)[https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps]
 - Create a New Registration
 - Add new Redirect URI = `http://localhost:3000`

From 80619474d854e3f1e1f8205920fa43cae513fc28 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Tue, 12 Jan 2021 08:46:22 +0100
Subject: [PATCH 18/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 0fd48dc7bf..2ad2d7c900 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -220,7 +220,7 @@ auth:
           $env: AUTH_MICROSOFT_TENANT_ID
 ```
 
-2. Create Microsoft Directory in Microsoft Portal
+2. Create a Microsoft App Registration in Microsoft Portal
 
 - Log into https://portal.azure.com
 - Navigate to (Azure Active Directory > App

From 0fed686aed8791e0ce24911df04193bb44b34e3e Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@roadie.io>
Date: Tue, 12 Jan 2021 08:47:27 +0100
Subject: [PATCH 19/50] Update docs/tutorials/quickstart-app-auth.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 2ad2d7c900..7475061b9e 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -176,7 +176,7 @@ auth:
           $env: AUTH_GOOGLE_CLIENT_SECRET
 ```
 
-2. Generate Google Application in Google Cloud console
+2. Generate Google Credentials in Google Cloud console
 
 - Log into https://console.cloud.google.com
 - Select or create a new project from the dropdown on the top bar

From 6d74776e1214f1e9ffe187f89cf909cbfdd027f1 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@hallila.com>
Date: Tue, 12 Jan 2021 08:55:45 +0100
Subject: [PATCH 20/50] Adds in more modifications based on PR comments

Run prettier.
Add heading level for list items.
Fix styling and nomenclature.
---
 docs/tutorials/quickstart-app-auth.md | 68 +++++++++++++++------------
 1 file changed, 38 insertions(+), 30 deletions(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 7475061b9e..205fcddb65 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -53,9 +53,9 @@ guest. Let's fix that now and add auth.
 
 # The Auth Configuration
 
-A default Backstage installation includes multiple authentication providers out of
-the box. The steps to enable new authentication providers in Backstage are very
-similar to each other, the biggest difference is usually configuring the
+A default Backstage installation includes multiple authentication providers out
+of the box. The steps to enable new authentication providers in Backstage are
+very similar to each other, the biggest difference is usually configuring the
 external authentication provider. Please see a subset of possible providers and
 instructions to integrate them below. Steps 1 & 2 are described separately for
 each provider and steps beyond that are common for all.
@@ -63,7 +63,7 @@ each provider and steps beyond that are common for all.
 <details><summary>Github</summary>
 <p>
 
-1. Open `app-config.yaml` and change it as follows
+### 1. Open `app-config.yaml` and change it as follows
 
 _from:_
 
@@ -88,7 +88,7 @@ auth:
         #  $env: AUTH_GITHUB_ENTERPRISE_INSTANCE_URL
 ```
 
-2. Generate a GitHub client ID and secret
+### 2. Generate a GitHub client ID and secret
 
 - Log into http://github.com
 - Navigate to (Settings > Developer Settings > OAuth Apps > New OAuth
@@ -106,7 +106,7 @@ auth:
 <details><summary>GitLab</summary>
 <p>
 
-1. Open `app-config.yaml` and change it as follows
+### 1. Open `app-config.yaml` and change it as follows
 
 _from:_
 
@@ -129,7 +129,7 @@ auth:
         audience: https://gitlab.com # Or your self-hosted Gitlab instance URL
 ```
 
-2. Generate a GitLab Application client ID and secret
+### 2. Generate a Gitlab Application client ID and secret
 
 - Log into GitLab
 - Navigate to (Profile > Settings >
@@ -137,12 +137,14 @@ auth:
 - Name your application
 - Set Callback URL = http://localhost:7000/api/auth/gitlab/handler/frame
 - Select the following values:
-  - `read_user (Read the authenticated user's personal information)`
-  - `read_repository (Allows read-only access to the repository)`
-  - `write_repository (Allows read-write access to the repository)`
-  - `openid (Authenticate using OpenID Connect)`
-  - `profile (Allows read-only access to the user's personal information using OpenID Connect)`
-  - `email (Allows read-only access to the user's primary email address using OpenID Connect)`
+  - `read_user` (Read the authenticated user's personal information)
+  - `read_repository` (Allows read-only access to the repository)
+  - `write_repository` (Allows read-write access to the repository)
+  - `openid` (Authenticate using OpenID Connect)
+  - `profile` (Allows read-only access to the user's personal information using
+    OpenID Connect)
+  - `email` (Allows read-only access to the user's primary email address using
+    OpenID Connect)
 - Click [Save application]
 - On the next page, copy and paste your new Application ID and Secret to
   environment variables defined in the `app-config.yaml` file,
@@ -154,7 +156,7 @@ auth:
 <details><summary>Google</summary>
 <p>
 
-1. Open `app-config.yaml` and change it as follows
+### 1. Open `app-config.yaml` and change it as follows
 
 _from:_
 
@@ -176,12 +178,14 @@ auth:
           $env: AUTH_GOOGLE_CLIENT_SECRET
 ```
 
-2. Generate Google Credentials in Google Cloud console
+### 2. Generate Google Credentials in Google Cloud console
 
 - Log into https://console.cloud.google.com
 - Select or create a new project from the dropdown on the top bar
 - Navigate to (APIs & Services >
   Credentials)[https://console.cloud.google.com/apis/credentials]
+- Click Create Credentials and select [OAuth client ID]
+- Select Web Application as the application type
 - Add new Authorised JavaScript origin = `http://localhost:3000`
 - Add new Authorised redirect URI =
   `http://localhost:7000/api/auth/google/handler/frame`
@@ -196,7 +200,7 @@ auth:
 <details><summary>Microsoft</summary>
 <p>
 
-1. Open `app-config.yaml` and change it as follows
+### 1. Open `app-config.yaml` and change it as follows
 
 _from:_
 
@@ -220,7 +224,7 @@ auth:
           $env: AUTH_MICROSOFT_TENANT_ID
 ```
 
-2. Create a Microsoft App Registration in Microsoft Portal
+### 2. Create a Microsoft App Registration in Microsoft Portal
 
 - Log into https://portal.azure.com
 - Navigate to (Azure Active Directory > App
@@ -244,7 +248,7 @@ auth:
 <details><summary>Auth0</summary>
 <p>
 
-1. Open `app-config.yaml` and change it as follows
+### 1. Open `app-config.yaml` and change it as follows
 
 _from:_
 
@@ -268,7 +272,7 @@ auth:
           $env: AUTH_AUTH0_DOMAIN_ID
 ```
 
-2. Create an Auth0 application in the Auth0 management console
+### 2. Create an Auth0 application in the Auth0 management console
 
 - Log into https://manage.auth0.com/dashboard/
 - Navigate to Applications
@@ -287,8 +291,9 @@ auth:
 </p>
 </details>
 
-3. Set environment variables in whatever fashion is easiest for you. I chose to
-   add mine to my `.zshrc` profile.
+### 3. Set environment variables in whatever fashion is easiest for you. I chose to
+
+add mine to my `.zshrc` profile.
 
 ```zsh
 # For macOS Catalina & Z Shell
@@ -300,7 +305,7 @@ export AUTH_GITHUB_CLIENT_SECRET=xxx
 # export AUTH_GITHUB_ENTERPRISE_INSTANCE_URL=https://github.{MY_BIZ}.com
 ```
 
-4. And of course I need to source that file.
+### 4. And of course I need to source that file.
 
 ```zsh
 # Loading the new variables
@@ -316,14 +321,16 @@ export AUTH_GITHUB_CLIENT_SECRET=xxx
 > ...
 ```
 
-5. Open and change \_root > packages > app > src >`App.tsx` to use correct
-   authentication provider reference
+### 5. Open and change _root > packages > app > src >_ `App.tsx` to use correct
+
+authentication provider reference
 
 ```tsx
 import { githubAuthApiRef, SignInPage } from '@backstage/core';
 ```
 
-Modify the imported reference based on the authentication method you selected above:
+Modify the imported reference based on the authentication method you selected
+above:
 
 | Auth Provider | Import Name         |
 | ------------- | ------------------- |
@@ -331,9 +338,9 @@ Modify the imported reference based on the authentication method you selected ab
 | Gitlab        | gitlabAuthApiRef    |
 | Google        | googleAuthApiRef    |
 | Microsoft     | microsoftAuthApiRef |
-| Auth0         | auth0AuthApiRef    |
+| Auth0         | auth0AuthApiRef     |
 
-6. In the same file, modify createApp
+### 6. In the same file, modify createApp
 
 Remember to modify the provider information based on the table above.
 
@@ -369,9 +376,10 @@ 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
 asked to authorize and then are redirected to the catalog page if all is well.
 
-For more information you can clone [the backstage-auth-example repository](https://github.com/RoadieHQ/backstage-auth-example).
- Each authentication setting
-is set up there on a branch named after the authentication provider.
+For more information you can clone
+[the backstage-auth-example repository](https://github.com/RoadieHQ/backstage-auth-example).
+Each authentication setting is set up there on a branch named after the
+authentication provider.
 
 # Where to go from here
 

From 6dee39ebe285f4f4013fbafad683c5da0a57b68d Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@hallila.com>
Date: Wed, 13 Jan 2021 09:16:58 +0100
Subject: [PATCH 21/50] Fix spelling.

---
 docs/tutorials/quickstart-app-auth.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 205fcddb65..14ed856c96 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -103,7 +103,7 @@ auth:
 </p>
 </details>
 
-<details><summary>GitLab</summary>
+<details><summary>Gitlab</summary>
 <p>
 
 ### 1. Open `app-config.yaml` and change it as follows

From e921fb2ec7428029748ad4d5a109a32ebde437ea Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@hallila.com>
Date: Wed, 13 Jan 2021 09:25:25 +0100
Subject: [PATCH 22/50] Fix GitHub stylization

---
 docs/tutorials/quickstart-app-auth.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 14ed856c96..4218940ef7 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -60,7 +60,7 @@ external authentication provider. Please see a subset of possible providers and
 instructions to integrate them below. Steps 1 & 2 are described separately for
 each provider and steps beyond that are common for all.
 
-<details><summary>Github</summary>
+<details><summary>GitHub</summary>
 <p>
 
 ### 1. Open `app-config.yaml` and change it as follows
@@ -334,7 +334,7 @@ above:
 
 | Auth Provider | Import Name         |
 | ------------- | ------------------- |
-| Github        | githubAuthApiRef    |
+| GitHub        | githubAuthApiRef    |
 | Gitlab        | gitlabAuthApiRef    |
 | Google        | googleAuthApiRef    |
 | Microsoft     | microsoftAuthApiRef |

From 37e4bf3473a1f399f572eb7bdcb636f57204ebd8 Mon Sep 17 00:00:00 2001
From: Jussi Hallila <jussi@hallila.com>
Date: Wed, 13 Jan 2021 10:12:40 +0100
Subject: [PATCH 23/50] Modifying GitLab text to be stylized

---
 docs/tutorials/quickstart-app-auth.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md
index 4218940ef7..1c661d274c 100644
--- a/docs/tutorials/quickstart-app-auth.md
+++ b/docs/tutorials/quickstart-app-auth.md
@@ -93,8 +93,8 @@ auth:
 - 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/api/auth/github
+- Set Homepage URL = `http://localhost:3000`
+- 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
   environment variables defined in the `app-config.yaml` file,
@@ -103,7 +103,7 @@ auth:
 </p>
 </details>
 
-<details><summary>Gitlab</summary>
+<details><summary>GitLab</summary>
 <p>
 
 ### 1. Open `app-config.yaml` and change it as follows
@@ -126,16 +126,16 @@ auth:
           $env: AUTH_GITLAB_CLIENT_ID
         clientSecret:
           $env: AUTH_GITLAB_CLIENT_SECRET
-        audience: https://gitlab.com # Or your self-hosted Gitlab instance URL
+        audience: https://gitlab.com # Or your self-hosted GitLab instance URL
 ```
 
-### 2. Generate a Gitlab Application client ID and secret
+### 2. Generate a GitLab Application client ID and secret
 
 - Log into GitLab
 - Navigate to (Profile > Settings >
   Applications)[https://gitlab.com/-/profile/applications]
 - Name your application
-- Set Callback URL = http://localhost:7000/api/auth/gitlab/handler/frame
+- Set Callback URL = `http://localhost:7000/api/auth/gitlab/handler/frame`
 - Select the following values:
   - `read_user` (Read the authenticated user's personal information)
   - `read_repository` (Allows read-only access to the repository)
@@ -335,7 +335,7 @@ above:
 | Auth Provider | Import Name         |
 | ------------- | ------------------- |
 | GitHub        | githubAuthApiRef    |
-| Gitlab        | gitlabAuthApiRef    |
+| GitLab        | gitlabAuthApiRef    |
 | Google        | googleAuthApiRef    |
 | Microsoft     | microsoftAuthApiRef |
 | Auth0         | auth0AuthApiRef     |

From dc33c518904549716a8af0cc5cc73fbe2f15388d Mon Sep 17 00:00:00 2001
From: Himanshu Mishra <himanshu@orkohunter.net>
Date: Wed, 13 Jan 2021 21:35:36 +0100
Subject: [PATCH 24/50] TechDocs: Use URL Reader in the out-of-the-box
 experience

It is time to start using URL Reader for the exmaple docs components we provide in the out-of-the-box experience (i.e. when users experience TechDocs by doing a git clone of this repository).

URL Reader makes the prepare step 8x faster.
---
 app-config.yaml                                               | 4 ++--
 catalog-info.yaml                                             | 2 +-
 .../{documented-component.yaml => catalog-info.yaml}          | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)
 rename plugins/techdocs-backend/examples/documented-component/{documented-component.yaml => catalog-info.yaml} (61%)

diff --git a/app-config.yaml b/app-config.yaml
index d2100801ae..ac9cf700df 100644
--- a/app-config.yaml
+++ b/app-config.yaml
@@ -178,9 +178,9 @@ catalog:
     # Example component for github-actions
     - type: url
       target: https://github.com/backstage/backstage/blob/master/plugins/github-actions/examples/sample.yaml
-    # Example component for techdocs
+    # Example component for TechDocs
     - type: url
-      target: https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend/examples/documented-component/documented-component.yaml
+      target: https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend/examples/documented-component/catalog-info.yaml
     # Backstage example APIs
     - type: url
       target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all-apis.yaml
diff --git a/catalog-info.yaml b/catalog-info.yaml
index 617d01093e..2144d1709c 100644
--- a/catalog-info.yaml
+++ b/catalog-info.yaml
@@ -6,7 +6,7 @@ metadata:
     Backstage is an open-source developer portal that puts the developer experience first.
   annotations:
     github.com/project-slug: backstage/backstage
-    backstage.io/techdocs-ref: github:https://github.com/backstage/backstage.git
+    backstage.io/techdocs-ref: url:https://github.com/backstage/backstage/tree/master
     lighthouse.com/website-url: https://backstage.io
 spec:
   type: library
diff --git a/plugins/techdocs-backend/examples/documented-component/documented-component.yaml b/plugins/techdocs-backend/examples/documented-component/catalog-info.yaml
similarity index 61%
rename from plugins/techdocs-backend/examples/documented-component/documented-component.yaml
rename to plugins/techdocs-backend/examples/documented-component/catalog-info.yaml
index 800116344f..d609866f9b 100644
--- a/plugins/techdocs-backend/examples/documented-component/documented-component.yaml
+++ b/plugins/techdocs-backend/examples/documented-component/catalog-info.yaml
@@ -4,7 +4,7 @@ metadata:
   name: documented-component
   description: A Service with TechDocs documentation
   annotations:
-    backstage.io/techdocs-ref: 'github:https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend/examples/documented-component'
+    backstage.io/techdocs-ref: 'url:https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend/examples/documented-component'
 spec:
   type: service
   lifecycle: experimental

From 3e9b38e288231d070777cd651cd3727b5705b4b6 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Sun, 10 Jan 2021 18:11:23 +0100
Subject: [PATCH 25/50] docs: initial incomplete composability docs

---
 docs/plugins/composability.md | 86 +++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 docs/plugins/composability.md

diff --git a/docs/plugins/composability.md b/docs/plugins/composability.md
new file mode 100644
index 0000000000..d85a557772
--- /dev/null
+++ b/docs/plugins/composability.md
@@ -0,0 +1,86 @@
+---
+id: composability
+title: New Composability System
+description:
+  Documentation and migration instructions for new composability APIs.
+---
+
+## Summary
+
+This page describes the new composability system that was recently introduced in
+Backstage. It describes the new system from the perspective of the existing
+patterns and APIs. As the new system is solidified and existing code is ported,
+this page will removed and replaced with a more direct description of the
+composability system.
+
+The core principle of the new composability system is that plugins should have
+clear boundaries and connections. It should isolate crashes within a plugin, but
+allow navigation between them. It should allow for plugins to be loaded only
+when needed, and enable plugins to provide extension point for other plugins to
+build upon. The composability system is also built with an app-first mindset,
+prioritizing simplicity and clarity in the app over plugins and core APIs.
+
+The new composability system isn't a single new API surface. It is a collection
+of patterns, new primitives, new APIs, and old APIs used in new ways. At the
+core is the new concept of Extensions, are exported by plugins for use in the
+app. There is a new primitive called component data, which is used to connect
+plugin and the app, and a new hook that provides a practical use of .
+
+## Component Data
+
+Component data is a new composability primitive that is introduced as a way to
+provide a new data dimension for React components. Data is attached to React
+components using a key, and is then readable from any JSX elements created with
+those components using the same key, as illustrated by the following example:
+
+```tsx
+const MyComponent = () => <h1>This is my component</h1>;
+attachComponentData(MyComponent, 'my.data', 5);
+
+const element = <MyComponent />;
+const myData = getComponentData(element, 'my.data');
+// myData === 5
+```
+
+The purpose of component data is to provide a method for embedding data that can
+be inspected before rendering elements. It's a pattern that is quite common
+among React libraries, and used for example by `react-router` and `material-ui`
+to discover properties of the child elements before rendering. Although in those
+libraries only the element type and props are typically inspected, while our
+component data adds more structured access and simplifies evolution by allowing
+for multiple different versions of a piece of data to be used at once.
+
+The main use-case
+
+## Extensions
+
+Extensions are what plugins export for use in an app. Most typically they are
+React components, but in practice they can be any kind of value. They are
+created using `create*Extension` functions, and wrapped with `plugin.provide()`
+in order to create the actual exported extension.
+
+The Backstage core API currently provides two different types of extension
+creators, `createComponentExtension`, and `createRoutableExtension`.
+
+### Extensions from a plugin's point of view
+
+Extensions are one of the primary methods to traverse the plugin boundary, and
+the way that plugins provide concrete content for use within an app. They
+replace existing component export concepts such as `Router` or `*Card`s for
+display on entity overview pages.
+
+### Using Extensions in an app
+
+TODO
+
+## RouteRefs, useRouteRef, and plugin routes and externalRoutes
+
+TODO
+
+## Binding external routes in the app
+
+TODO
+
+## New catalog components, EntitySwitch & EntityLayout, and how to use those in the app
+
+TODO

From 492258d2a10d83fba72d38e5101dc81b0f8795c7 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Tue, 12 Jan 2021 20:23:27 +0100
Subject: [PATCH 26/50] docs: lotsa more composability docs

---
 .github/styles/vocab.txt      |   2 +
 docs/plugins/composability.md | 255 +++++++++++++++++++++++++++++++---
 2 files changed, 234 insertions(+), 23 deletions(-)

diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt
index a71887f796..6c38cf638a 100644
--- a/.github/styles/vocab.txt
+++ b/.github/styles/vocab.txt
@@ -183,6 +183,8 @@ rollbar
 Rollbar
 Rollup
 Rosaceae
+routable
+Routable
 rst
 rsync
 rugvip
diff --git a/docs/plugins/composability.md b/docs/plugins/composability.md
index d85a557772..5c96b88cee 100644
--- a/docs/plugins/composability.md
+++ b/docs/plugins/composability.md
@@ -26,7 +26,12 @@ core is the new concept of Extensions, are exported by plugins for use in the
 app. There is a new primitive called component data, which is used to connect
 plugin and the app, and a new hook that provides a practical use of .
 
-## Component Data
+## New Concepts
+
+This section is a brief look into all the new and updated concepts that were put
+in place to support the new composability system.
+
+### Component Data
 
 Component data is a new composability primitive that is introduced as a way to
 provide a new data dimension for React components. Data is attached to React
@@ -43,44 +48,248 @@ const myData = getComponentData(element, 'my.data');
 ```
 
 The purpose of component data is to provide a method for embedding data that can
-be inspected before rendering elements. It's a pattern that is quite common
-among React libraries, and used for example by `react-router` and `material-ui`
-to discover properties of the child elements before rendering. Although in those
-libraries only the element type and props are typically inspected, while our
-component data adds more structured access and simplifies evolution by allowing
-for multiple different versions of a piece of data to be used at once.
+be inspected before rendering elements. Element inspection is a pattern that is
+quite common among React libraries, and used for example by `react-router` and
+`material-ui` to discover properties of the child elements before rendering.
+Though in those libraries only the element type and props are typically
+inspected, while our component data adds more structured access and simplifies
+evolution by allowing for multiple different versions of a piece of data to be
+used at once.
 
-The main use-case
+The initial use-cases for component data is support route and plugin discovery
+through elements in the app. Through this we allow for the React element tree in
+the app to be the source of truth, both for which plugins are used and all
+top-level plugin routes in the app. The use of component data is not limited to
+these use-cases though, as it can be used as a primitive to create new
+abstractions as well.
 
-## Extensions
+### Extensions
 
 Extensions are what plugins export for use in an app. Most typically they are
 React components, but in practice they can be any kind of value. They are
 created using `create*Extension` functions, and wrapped with `plugin.provide()`
 in order to create the actual exported extension.
 
-The Backstage core API currently provides two different types of extension
-creators, `createComponentExtension`, and `createRoutableExtension`.
+The extension type is dead simple:
 
-### Extensions from a plugin's point of view
+```ts
+export type Extension<T> = {
+  expose(plugin: BackstagePlugin<any, any>): T;
+};
+```
+
+The power of extensions comes from the ability of various actors to hook into
+their usage. The creation and plugin wrapping is controlled by whoever owns the
+creation function, the Backstage core is able to hook into the process of
+exposing the extension outside the plugin, and in the end the app controls the
+usage of the extension.
+
+The Backstage core API currently provides two different types of extension
+creators, `createComponentExtension`, and `createRoutableExtension`. Component
+extensions are plain react component with no particular requirements, such as
+cards for entity overview pages. The component will be exported more or less as
+is, but is wrapped up to provide things like an error boundary, lazy loading,
+and a plugin context.
+
+Routable extensions build on top of component extensions and are used for any
+component that should be rendered at a specific route path, such as full pages
+or entity page tab content. When creating a routable extension you need to
+supply a `RouteRef` as `mountPoint`. The mount point will be the handle of the
+component for the outside world, and is used by other components and plugins
+that wish to link to the routable component.
+
+As of now there are only two extension creation functions, but it is possible to
+add more of them in the future, both in the core library and in plugins that
+wish to provide an extension point for other plugins to build upon. Extensions
+are also not tied to React, and can both be used to model generic JavaScript
+concepts, as well as potentially bridge to rendering libraries and web
+frameworks other than React.
+
+### Extensions from a Plugin's Point of View
 
 Extensions are one of the primary methods to traverse the plugin boundary, and
 the way that plugins provide concrete content for use within an app. They
 replace existing component export concepts such as `Router` or `*Card`s for
 display on entity overview pages.
 
-### Using Extensions in an app
+It is recommended to create the exported extensions either in the top-level
+`plugin.ts` file, or in a dedicated `extensions.ts` (or `.tsx`) file. That file
+should not contain the bulk of the implementation though, and in fact, if the
+extension is a React component it is recommended to lazy-load the actual
+component. Component extensions support lazy loading out of the box using the
+`lazy` component declaration, for example:
+
+```ts
+export const EntityFooCard = plugin.provide(
+  createComponentExtension({
+    component: {
+      lazy: () => import('./components/FooCard').then(m => m.FooCard),
+    },
+  }),
+);
+```
+
+Routable extensions even enforce lazy loading, for example:
+
+```ts
+export const FooPage = plugin.provide(
+  createRoutableExtension({
+    component: () => import('./components/FooPage').then(m => m.FooPage),
+    mountPoint: fooRouteRef,
+  }),
+);
+```
+
+### Using Extensions in an App
+
+Right now all extensions are modelled as React components. The usage of these
+extension is like regular usage of any React components, with one important
+difference. Extensions must be all be part of a single React element tree
+spanning from the root `AppProvider`.
+
+For example, the following app code does **NOT** work:
+
+```tsx
+const AppRoutes = () => (
+  <Routes>
+    <Route path="/foo" element={<FooPage />} />
+    <Route path="/bar" element={<BarPage />} />
+  </Routes>
+);
+
+const App = () => (
+  <AppProvider>
+    <AppRouter>
+      <Root>
+        <AppRoutes />
+      </Root>
+    </AppRouter>
+  </AppProvider>
+);
+```
+
+But it is simple to fix! Simply make sure that you don't create any intermediate
+components in the app, for example like this:
+
+```tsx
+const appRoutes = (
+  <Routes>
+    <Route path="/foo" element={<FooPage />} />
+    <Route path="/bar" element={<BarPage />} />
+  </Routes>
+);
+
+const App = () => (
+  <AppProvider>
+    <AppRouter>
+      <Root>{appRoutes}</Root>
+    </AppRouter>
+  </AppProvider>
+);
+```
+
+### New Routing System
+
+A big piece of what is enabled by moving over to this new composability system
+is to make `RouteRef`s useful. The `RouteRef`s no longer have their own path, in
+fact the only required parameter is currently a `title`. Instead of assigning a
+path to each `RouteRef` and possibly overriding these paths in the app, the
+concrete `path` for each `RouteRef` is discovered based on the element tree in
+the app. Let's consider the following example:
+
+```tsx
+<Routes>
+  <Route path="/foo" element={<FooPage />} />
+  <Route path="/bar" element={<BarPage />} />
+</Routes>
+```
+
+We'll assume that `FooPage` and `BarPage` are routable extensions, exported by
+the `fooPlugin` and `barPlugin` respectively. Since the `FooPage` is a routable
+extension it has a `RouteRef` assigned as its mount point, which we'll refer to
+as `fooRootRouteRef`.
+
+Given the above example, the `fooRootRouteRef` will be associated with the
+`'/foo'` route. The path is no longer accessible via the `path` property of the
+`RouteRef` though, as the routing structure is tied to the app's react tree. We
+instead use the new `useRouteRef` hook if we want to create a concrete link to
+the page. The `useRouteRef` hook takes a single `RouteRef` as its only
+parameter, and returns a function that is called to create the URL.
+
+Now let's assume that we want to link from the `BarPage` to the `FooPage`.
+Before the introduction of the new composability system, we would do this by
+importing the `fooRootRouteRef` from the `fooPlugin`. This created an
+unnecessary dependency on the plugin, and also provided little flexibility
+allowing the app to tie plugins together rather than the plugins themselves. To
+handle this, we introduce the concept of `ExternalRouteRef`s. Much like regular
+route refs, they can be passed to `useRouteRef` to create concrete URLs, but
+they can not be used as mount points in routable component and instead have to
+be associated with an actual using route bindings in the app.
+
+The `ExternalRouteRef` inside the `barPlugin` should also not be opinionated
+about what it is linking to either, allowing the app to decide the final target.
+It should however provide context in how the link is presented or used, to make
+it easier to understand the flow of the app. If the `BarPage` for example wants
+to link to an external page in the header, it might declare an
+`ExternalRouteRef` similar to this:
+
+```ts
+const headerLinkRouteRef = createExternalRouteRef();
+```
+
+### Binding External Routes in the App
+
+The association of external routes are controlled by the app. Each
+`ExternalRouteRef` of a plugin is bound to an actual `RouteRef`, usually from
+another plugin. The binding process happens once att app startup, and is then
+used through the lifetime of the app to help resolve concrete route paths.
+
+Using the above example of the `BarPage` linking to the `FooPage`, we might do
+something like this in the app:
+
+```ts
+createApp({
+  bindRoutes({ bind }) {
+    bind(barPlugin.externalRoutes, {
+      headerLink: fooPlugin.routes.root,
+    });
+  },
+});
+```
+
+Given the above binding, using `useRouteRef(external)`
+
+Note that we are not importing and using the `RouteRef`s directly, and instead
+rely on the plugin instance to access routes of the plugins. This is a new
+convention that was introduced to provide better namespacing and discoverability
+of routes, as well as reduce the number of different things exported from each
+plugin package. The route references would be supplied to `createPlugin` like
+this:
+
+```ts
+// In foo-plugin
+export const fooPlugin = createPlugin({
+  routes: {
+    root: fooRootRouteRef,
+  },
+  ...
+})
+
+// In bar-plugin
+export const barPlugin = createPlugin({
+  externalRoutes: {
+    headerLink: headerLinkRouteRef,
+  },
+  ...
+})
+```
+
+### New Catalog Components
+
+EntitySwitch & EntityLayout, and how to use those in the app
 
 TODO
 
-## RouteRefs, useRouteRef, and plugin routes and externalRoutes
+## Porting Existing Plugins
 
-TODO
-
-## Binding external routes in the app
-
-TODO
-
-## New catalog components, EntitySwitch & EntityLayout, and how to use those in the app
-
-TODO
+## Porting Existing Apps

From 70d8653bdad5649399bcae8d146922bdc3d7b2d5 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 13 Jan 2021 23:52:10 +0100
Subject: [PATCH 27/50] docs/composability: the rest of the f***ing owl

---
 docs/plugins/composability.md | 403 +++++++++++++++++++++++++++++-----
 1 file changed, 346 insertions(+), 57 deletions(-)

diff --git a/docs/plugins/composability.md b/docs/plugins/composability.md
index 5c96b88cee..3e38f3376e 100644
--- a/docs/plugins/composability.md
+++ b/docs/plugins/composability.md
@@ -16,15 +16,17 @@ composability system.
 The core principle of the new composability system is that plugins should have
 clear boundaries and connections. It should isolate crashes within a plugin, but
 allow navigation between them. It should allow for plugins to be loaded only
-when needed, and enable plugins to provide extension point for other plugins to
+when needed, and enable plugins to provide extension points for other plugins to
 build upon. The composability system is also built with an app-first mindset,
-prioritizing simplicity and clarity in the app over plugins and core APIs.
+prioritizing simplicity and clarity in the app over that in the plugins and core
+APIs.
 
 The new composability system isn't a single new API surface. It is a collection
-of patterns, new primitives, new APIs, and old APIs used in new ways. At the
-core is the new concept of Extensions, are exported by plugins for use in the
-app. There is a new primitive called component data, which is used to connect
-plugin and the app, and a new hook that provides a practical use of .
+of patterns, primitives, new APIs, and old APIs used in new ways. At the core is
+the new concept of extensions, which are exported by plugins for use in the app.
+There is also a new primitive called component data, which assists in the
+conversion to a more declarative app. The `RouteRef`s now have a clear purpose
+as well, and can be used route to pages in a flexible way.
 
 ## New Concepts
 
@@ -36,7 +38,7 @@ in place to support the new composability system.
 Component data is a new composability primitive that is introduced as a way to
 provide a new data dimension for React components. Data is attached to React
 components using a key, and is then readable from any JSX elements created with
-those components using the same key, as illustrated by the following example:
+those components, using the same key, as illustrated by the following example:
 
 ```tsx
 const MyComponent = () => <h1>This is my component</h1>;
@@ -51,26 +53,26 @@ The purpose of component data is to provide a method for embedding data that can
 be inspected before rendering elements. Element inspection is a pattern that is
 quite common among React libraries, and used for example by `react-router` and
 `material-ui` to discover properties of the child elements before rendering.
-Though in those libraries only the element type and props are typically
+Although in those libraries only the element type and props are typically
 inspected, while our component data adds more structured access and simplifies
 evolution by allowing for multiple different versions of a piece of data to be
-used at once.
+used and interpreted at once.
 
 The initial use-cases for component data is support route and plugin discovery
 through elements in the app. Through this we allow for the React element tree in
-the app to be the source of truth, both for which plugins are used and all
-top-level plugin routes in the app. The use of component data is not limited to
-these use-cases though, as it can be used as a primitive to create new
+the app to be the source of truth, both for which plugins are used, as well as
+all top-level plugin routes in the app. The use of component data is not limited
+to these use-cases though, as it can be used as a primitive to create new
 abstractions as well.
 
 ### Extensions
 
 Extensions are what plugins export for use in an app. Most typically they are
-React components, but in practice they can be any kind of value. They are
-created using `create*Extension` functions, and wrapped with `plugin.provide()`
-in order to create the actual exported extension.
+React components, but in practice they can be any kind of JavaScript value. They
+are created using `create*Extension` functions, and wrapped with
+`plugin.provide()` in order to create the actual exported extension.
 
-The extension type is dead simple:
+The extension type is a simple one:
 
 ```ts
 export type Extension<T> = {
@@ -86,14 +88,14 @@ usage of the extension.
 
 The Backstage core API currently provides two different types of extension
 creators, `createComponentExtension`, and `createRoutableExtension`. Component
-extensions are plain react component with no particular requirements, such as
-cards for entity overview pages. The component will be exported more or less as
-is, but is wrapped up to provide things like an error boundary, lazy loading,
-and a plugin context.
+extensions are plain React component with no particular requirements, for
+example a card for an entity overview page. The component will be exported more
+or less as is, but is wrapped to provide things like an error boundary, lazy
+loading, and a plugin context.
 
 Routable extensions build on top of component extensions and are used for any
-component that should be rendered at a specific route path, such as full pages
-or entity page tab content. When creating a routable extension you need to
+component that should be rendered at a specific route path, such as top-level
+pages or entity page tab content. When creating a routable extension you need to
 supply a `RouteRef` as `mountPoint`. The mount point will be the handle of the
 component for the outside world, and is used by other components and plugins
 that wish to link to the routable component.
@@ -129,7 +131,8 @@ export const EntityFooCard = plugin.provide(
 );
 ```
 
-Routable extensions even enforce lazy loading, for example:
+Routable extensions even enforce lazy loading, as it is the only way to provide
+a component:
 
 ```ts
 export const FooPage = plugin.provide(
@@ -144,8 +147,8 @@ export const FooPage = plugin.provide(
 
 Right now all extensions are modelled as React components. The usage of these
 extension is like regular usage of any React components, with one important
-difference. Extensions must be all be part of a single React element tree
-spanning from the root `AppProvider`.
+difference. Extensions must all be part of a single React element tree spanning
+from the root `AppProvider`.
 
 For example, the following app code does **NOT** work:
 
@@ -168,8 +171,8 @@ const App = () => (
 );
 ```
 
-But it is simple to fix! Simply make sure that you don't create any intermediate
-components in the app, for example like this:
+But in this case it is simple to fix! Simply be sure to not create any
+intermediate components in the app, for example like this:
 
 ```tsx
 const appRoutes = (
@@ -198,10 +201,12 @@ concrete `path` for each `RouteRef` is discovered based on the element tree in
 the app. Let's consider the following example:
 
 ```tsx
-<Routes>
-  <Route path="/foo" element={<FooPage />} />
-  <Route path="/bar" element={<BarPage />} />
-</Routes>
+const appRoutes = (
+  <Routes>
+    <Route path="/foo" element={<FooPage />} />
+    <Route path="/bar" element={<BarPage />} />
+  </Routes>
+);
 ```
 
 We'll assume that `FooPage` and `BarPage` are routable extensions, exported by
@@ -214,24 +219,32 @@ Given the above example, the `fooRootRouteRef` will be associated with the
 `RouteRef` though, as the routing structure is tied to the app's react tree. We
 instead use the new `useRouteRef` hook if we want to create a concrete link to
 the page. The `useRouteRef` hook takes a single `RouteRef` as its only
-parameter, and returns a function that is called to create the URL.
+parameter, and returns a function that is called to create the URL. For example
+like this:
+
+```tsx
+const MyComponent = () => {
+  const fooRoute = useRouteRef(fooRouteRef);
+  return <a href={fooRoute()}>Link to Foo</a>;
+};
+```
 
 Now let's assume that we want to link from the `BarPage` to the `FooPage`.
 Before the introduction of the new composability system, we would do this by
 importing the `fooRootRouteRef` from the `fooPlugin`. This created an
-unnecessary dependency on the plugin, and also provided little flexibility
-allowing the app to tie plugins together rather than the plugins themselves. To
-handle this, we introduce the concept of `ExternalRouteRef`s. Much like regular
-route refs, they can be passed to `useRouteRef` to create concrete URLs, but
-they can not be used as mount points in routable component and instead have to
-be associated with an actual using route bindings in the app.
+unnecessary dependency on the plugin, and also provided little flexibility in
+allowing the app to tie plugins together, with the links instead being dictated
+by the plugins themselves. To solve this, we introduce `ExternalRouteRef`s. Much
+like regular route references, they can be passed to `useRouteRef` to create
+concrete URLs, but they can not be used as mount points in routable component
+and instead have to be associated with a target route using route bindings in
+the app.
 
-The `ExternalRouteRef` inside the `barPlugin` should also not be opinionated
-about what it is linking to either, allowing the app to decide the final target.
-It should however provide context in how the link is presented or used, to make
-it easier to understand the flow of the app. If the `BarPage` for example wants
-to link to an external page in the header, it might declare an
-`ExternalRouteRef` similar to this:
+We create a new `ExternalRouteRef` inside the `barPlugin`, using a neutral name
+that describes its role in the plugin rather than a specific plugin page that it
+might be linking to, allowing the app to decide the final target. If the
+`BarPage` for example wants to link to an external page in the header, it might
+declare an `ExternalRouteRef` similar to this:
 
 ```ts
 const headerLinkRouteRef = createExternalRouteRef();
@@ -239,10 +252,11 @@ const headerLinkRouteRef = createExternalRouteRef();
 
 ### Binding External Routes in the App
 
-The association of external routes are controlled by the app. Each
-`ExternalRouteRef` of a plugin is bound to an actual `RouteRef`, usually from
-another plugin. The binding process happens once att app startup, and is then
-used through the lifetime of the app to help resolve concrete route paths.
+The association of external routes is controlled by the app. Each
+`ExternalRouteRef` of a plugin should be<- bound to an actual `RouteRef`,
+usually from another plugin. The binding process happens once att app startup,
+and is then used through the lifetime of the app to help resolve concrete route
+paths.
 
 Using the above example of the `BarPage` linking to the `FooPage`, we might do
 something like this in the app:
@@ -257,14 +271,15 @@ createApp({
 });
 ```
 
-Given the above binding, using `useRouteRef(external)`
+Given the above binding, using `useRouteRef(headerLinkRouteRef)` within the
+`barPlugin` will let us create a link whatever path the `FooPage` is mounted at.
 
-Note that we are not importing and using the `RouteRef`s directly, and instead
-rely on the plugin instance to access routes of the plugins. This is a new
-convention that was introduced to provide better namespacing and discoverability
-of routes, as well as reduce the number of different things exported from each
-plugin package. The route references would be supplied to `createPlugin` like
-this:
+Note that we are not importing and using the `RouteRef`s directly in the app,
+and instead rely on the plugin instance to access routes of the plugins. This is
+a new convention that was introduced to provide better namespacing and
+discoverability of routes, as well as reduce the number of separate exports from
+each plugin package. The route references would be supplied to `createPlugin`
+like this:
 
 ```ts
 // In foo-plugin
@@ -284,12 +299,286 @@ export const barPlugin = createPlugin({
 })
 ```
 
+Also note that you almost always want to create the route references themselves
+in a different file than the one that creates the plugin instance, for example a
+top-level `routes.ts`. This is to avoid circular imports when you use the route
+references from other parts of the app.
+
+### Parameterized Routes
+
+A new addition to `RouteRef`s is the possibility of adding named and typed
+parameters. Parameters are declared at creation, and will enforce presence of
+the parameters in the path in the app, and require them as a parameter when
+using `useRouteRef`.
+
+The following is an example of creation and usage of a parameterized route:
+
+```tsx
+// Creation of a parameterized route
+const myRouteRef = createRouteRef({
+  title: 'My Named Route',
+  params: ['name']
+})
+
+// In the app, where MyPage is a routable extension with myRouteRef set as mountPoint
+<Route path='/my-page/:name' element={<MyPage />}/>
+
+// Usage within a component
+const myRoute = useRouteRef(myRouteRef)
+return (
+  <div>
+    <a href={myRoute({name: 'a'})}>A</a>
+    <a href={myRoute({name: 'b'})}>B</a>
+  </div>
+)
+```
+
+It is currently not possible to have parameterized `ExternalRouteRef`s, or to
+bind an external route to a parameterized route, although this may be added in
+the future if needed.
+
 ### New Catalog Components
 
-EntitySwitch & EntityLayout, and how to use those in the app
+The established pattern for selecting what plugins should be available on each
+catalog page is to use custom components in the app, with logic embedded in the
+render function. Typically this takes form as a component that either receives
+the entity via props or uses the `useEntity` hook to retrieve the selected
+entity. A `switch` or `if` / `else if` chain is then used to select what
+children should be rendered based on information in the entity.
 
-TODO
+This pattern will no longer work with the new composability system, and in
+general is very difficult to build any form declarative model around, as it
+depends on runtime execution. To help replace existing code, a new
+`EntitySwitch` component has been added to the `@backstage/catalog` plugin,
+which grabs the selected entity from context, and selects at most one element to
+render using a list of `EntitySwitch.Case`s children.
+
+For example, if you want all entities of kind `"Template"` to be rendered with a
+`MyTemplate` component, and all other entities to be rendered with a `MyOther`
+component, you would do the following:
+
+```tsx
+<EntitySwitch>
+  <EntitySwitch.Case if={isKind('template')}>
+    <MyTemplate />
+  </EntitySwitch.Case>
+
+  <EntitySwitch.Case>
+    <MyTemplate />
+  </EntitySwitch.Case>
+</EntitySwitch>
+
+// Shorter form if desired:
+<EntitySwitch>
+  <EntitySwitch.Case if={isKind('template')} children={<MyTemplate />}/>
+  <EntitySwitch.Case children={<MyTemplate />}/>
+</EntitySwitch>
+```
+
+The `EntitySwitch` component will render the children of the first
+`EntitySwitch.Case` that returns `true` when the selected entity is passed to
+the function of the `if` prop. If none of the cases match, no children will be
+rendered, and if a case doesn't specify an `if` filter function, it will always
+match. The `if` property is simply a function of the type
+`(entity: Entity) => boolean`, for example, `isKind` can be implemented like
+this:
+
+```ts
+function isKind(kind: string) {
+  return (entity: Entity) => entity.kind.toLowerCase() === kind.toLowerCase();
+}
+```
+
+The `@backstage/catalog` plugin provides a couple of built-in conditions,
+`isKind`, `isComponentType`, and `isNamespace`.
+
+In addition to the `EntitySwitch` component, the catalog plugin also exports a
+new `EntityLayout` component. It is a tweaked version and replacement for the
+`EntityPageLayout` component, and is introduced more in depth in the app
+migration section below.
 
 ## Porting Existing Plugins
 
+There are a couple of high-level steps to porting an existing plugin to the new
+composability system:
+
+- Remove usage of `router.addRoute` or `router.registerRoute` within
+  `createPlugin`, and export the page components as routable extensions instead.
+- Switch any `Router` export to instead be a routable extension.
+- Change any plain component exports, such as catalog overview cards, to be
+  component extensions.
+- Stop exporting `RouteRef`s and instead pass them to `createPlugin`.
+- Stop accepting `RouteRef`s as props or importing them from other plugins,
+  instead create an `ExternalRouteRef` as a replacement, and pass it to
+  `createPlugin.`
+- Rename any other exported symbols according to the naming pattern table below.
+
+Note that removing the existing exports and configuration is a breaking change
+in any plugin. If backwards compatibility is needed the existing code be
+deprecated while making the new additions, to then be removed at a later point.
+
+### Naming Patterns
+
+Many export naming patterns have been changed to avoid import aliases and to
+clarify intent. Refer to the following table to formulate the new name:
+
+| Description          | Existing Pattern           | New Pattern     | Examples                                       |
+| -------------------- | -------------------------- | --------------- | ---------------------------------------------- |
+| Top-level Pages      | Router                     | \*Page          | CatalogIndexPage, SettingsPage, LighthousePage |
+| Entity Tab Content   | Router                     | Entity\*Content | EntityJenkinsContent, EntityKubernetesContent  |
+| Entity Overview Card | \*Card                     | Entity\*Card    | EntitySentryCard, EntityPagerDutyCard          |
+| Entity Conditional   | isPluginApplicableToEntity | is\*Available   | isPagerDutyAvailable, isJenkinsAvailable       |
+| Plugin Instance      | plugin                     | \*Plugin        | jenkinsPlugin, catalogPlugin                   |
+
 ## Porting Existing Apps
+
+The first step of porting any app is to replace the root `Routes` component with
+`FlatRoutes` from `@backstage/core`. As opposed to the `Routes` component,
+`FlatRoutes` only considers the first level of `Route` components in its
+children, and provides any additional children to the outlet of the route. It
+also removes the need to append `"/*"` to paths, as it is added automatically.
+
+```diff
+const AppRoutes = () => (
+-  <Routes>
++  <FlatRoutes>
+    ...
+-    <Route path="/docs/*" element={<DocsRouter />} />
++    <Route path="/docs" element={<DocsRouter />} />
+    ...
+-  </Routes>
++  </FlatRoutes>
+);
+```
+
+The next step should be to switch from using `EntityPageLayout` to
+`EntityLayout`, as this can also be done without waiting for plugins to be
+ported. You should also replace the top-level `Router` from the catalog plugin
+with the separate `CatalogIndexPage` and `CatalogEntityPage` extensions that
+have been added to the catalog:
+
+```diff
+-<Route
+-  path={`${catalogRouteRef.path}/*`}
+-  element={<CatalogRouter EntityPage={EntityPage} />}
+-/>
++<Route path="/catalog" element={<CatalogIndexPage />} />
++<Route
++  path="/catalog/:namespace/:kind/:name"
++  element={<CatalogEntityPage />}
++>
++  <EntityPage />
++</Route>
+```
+
+At that point you should flatten out the element tree as much as possible in the
+app, removing any intermediate components. At the top level this should usually
+be straightforward, but when reaching the catalog entity pages you may need to
+wait for some plugins to be migrated. This is because it is no longer possible
+to pass in the selected entity through component props, and it should be picked
+up from context inside the plugin instead. See the sections below for how to
+carry out migrations of some common entity page patterns.
+
+Once the app element tree doesn't contain any intermediate components, and all
+plugin imports have been switched to extensions rather than plain components,
+the app has been fully ported.
+
+### Switching from EntityPageLayout to EntityLayout
+
+The existing `EntityPageLayout` is replaced by the new `EntityLayout` component,
+which has a slightly different pattern for expressing the contents and paths.
+
+Porting from the old to the new API is just a matter of moving some things
+around. For example, given the following existing code:
+
+```tsx
+<EntityPageLayout>
+  <EntityPageLayout.Content
+    path="/"
+    title="Overview"
+    element={<ComponentOverviewContent entity={entity} />}
+  />
+  <EntityPageLayout.Content
+    path="/sentry"
+    title="Sentry"
+    element={<SentryRouter entity={entity} />}
+  />
+  <EntityPageLayout.Content
+    path="/kubernetes/*"
+    title="Kubernetes"
+    element={<KubernetesRouter entity={entity} />}
+  />
+</EntityPageLayout>
+```
+
+It would be ported to this:
+
+```tsx
+<EntityLayout>
+  <EntityLayout.Route path="/" title="Overview">
+    <ComponentOverviewContent entity={entity} />}
+  </EntityLayout.Route>
+
+  <EntityLayout.Route path="/sentry" title="Sentry">
+    <SentryRouter entity={entity} />}
+  </EntityLayout.Route>
+
+  <EntityLayout.Route path="/kubernetes" title="Kubernetes">
+    <KubernetesRouter entity={entity} />}
+  </EntityLayout.Route>
+</EntityLayout>
+```
+
+In addition to the renaming, the `element` prop has been moved to `children`.
+Also note that the `/*` suffix has been remove from the `"/kubernetes"` path, as
+it's now added automatically.
+
+Usage of the `EntityLayout` component is required to be able to properly
+discover routes, and so it is required to apply this change before you can start
+using routable entity content extensions from plugins.
+
+### Porting Entity Pages
+
+The established pattern in the app is to use custom components in order to
+select what plugin components to render for a given entity. The new
+`EntitySwitch` component introduced above is what is intended to replace this
+pattern, now that the entire app needs to be rendered as a single element tree.
+For example, given the following existing code:
+
+```tsx
+export const EntityPage = () => {
+  const { entity } = useEntity();
+
+  switch (entity?.kind?.toLowerCase()) {
+    case 'component':
+      return <ComponentEntityPage entity={entity} />;
+    case 'api':
+      return <ApiEntityPage entity={entity} />;
+    case 'group':
+      return <GroupEntityPage entity={entity} />;
+    case 'user':
+      return <UserEntityPage entity={entity} />;
+    default:
+      return <DefaultEntityPage entity={entity} />;
+  }
+};
+```
+
+It would be migrated to this:
+
+```tsx
+export const entityPage = (
+  <EntitySwitch>
+    <EntitySwitch.Case if={isKind('component')} children={componentPage} />
+    <EntitySwitch.Case if={isKind('api')} children={apiPage} />
+    <EntitySwitch.Case if={isKind('group')} children={groupPage} />
+    <EntitySwitch.Case if={isKind('user')} children={userPage} />
+    <EntitySwitch.Case children={defaultPage} />
+  </EntitySwitch>
+);
+```
+
+Note that for example `<ComponentEntityPage ... />` has been changed to simply
+`componentPage`, that is because just like the `EntityPage` component, the
+`ComponentEntityPage` also needs to be ported to be an element rather a
+component in a similar way.

From 72ce0f8b163b4d01a309064cad99f6f5af20e36e Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 14 Jan 2021 02:04:57 +0100
Subject: [PATCH 28/50] docs/composability: include in sidebar and add note
 about purpose

---
 docs/plugins/composability.md | 11 ++++++-----
 microsite/sidebars.json       |  1 +
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/docs/plugins/composability.md b/docs/plugins/composability.md
index 3e38f3376e..e6f00d2374 100644
--- a/docs/plugins/composability.md
+++ b/docs/plugins/composability.md
@@ -1,6 +1,6 @@
 ---
 id: composability
-title: New Composability System
+title: Composability System Migration
 description:
   Documentation and migration instructions for new composability APIs.
 ---
@@ -8,10 +8,11 @@ description:
 ## Summary
 
 This page describes the new composability system that was recently introduced in
-Backstage. It describes the new system from the perspective of the existing
-patterns and APIs. As the new system is solidified and existing code is ported,
-this page will removed and replaced with a more direct description of the
-composability system.
+Backstage, and it does so from the perspective of the existing patterns and
+APIs. As the new system is solidified and existing code is ported, this page
+will removed and replaced with a more direct description of the composability
+system. For now, the primary purpose of this documentation is to aid in the
+migration of existing plugins, but it does cover the migration of apps as well.
 
 The core principle of the new composability system is that plugins should have
 clear boundaries and connections. It should isolate crashes within a plugin, but
diff --git a/microsite/sidebars.json b/microsite/sidebars.json
index 3d6417cc65..05e421cb19 100644
--- a/microsite/sidebars.json
+++ b/microsite/sidebars.json
@@ -95,6 +95,7 @@
       "plugins/plugin-development",
       "plugins/structure-of-a-plugin",
       "plugins/integrating-plugin-into-service-catalog",
+      "plugins/composability",
       {
         "type": "subcategory",
         "label": "Backends and APIs",

From a1f587c8614adc9d3b81089b28e60595875c7f9e Mon Sep 17 00:00:00 2001
From: Adam Harvey <adam.harvey@dxc.com>
Date: Thu, 14 Jan 2021 01:01:37 -0500
Subject: [PATCH 29/50] Support HTTP 400 Bad Request

---
 plugins/kubernetes-backend/src/service/KubernetesFetcher.ts | 2 ++
 plugins/kubernetes-backend/src/types/types.ts               | 1 +
 2 files changed, 3 insertions(+)

diff --git a/plugins/kubernetes-backend/src/service/KubernetesFetcher.ts b/plugins/kubernetes-backend/src/service/KubernetesFetcher.ts
index d9c6ee6d1a..991174e78a 100644
--- a/plugins/kubernetes-backend/src/service/KubernetesFetcher.ts
+++ b/plugins/kubernetes-backend/src/service/KubernetesFetcher.ts
@@ -74,6 +74,8 @@ function fetchResultsToResponseWrapper(
 
 const statusCodeToErrorType = (statusCode: number): KubernetesErrorTypes => {
   switch (statusCode) {
+    case 400:
+      return 'BAD_REQUEST';
     case 401:
       return 'UNAUTHORIZED_ERROR';
     case 500:
diff --git a/plugins/kubernetes-backend/src/types/types.ts b/plugins/kubernetes-backend/src/types/types.ts
index 9f0b90c032..cf6576153b 100644
--- a/plugins/kubernetes-backend/src/types/types.ts
+++ b/plugins/kubernetes-backend/src/types/types.ts
@@ -135,6 +135,7 @@ export interface KubernetesClustersSupplier {
 }
 
 export type KubernetesErrorTypes =
+  | 'BAD_REQUEST'
   | 'UNAUTHORIZED_ERROR'
   | 'SYSTEM_ERROR'
   | 'UNKNOWN_ERROR';

From b2fc74ea168004dde06f76a144c01fd26b7122a9 Mon Sep 17 00:00:00 2001
From: Himanshu Mishra <himanshu@orkohunter.net>
Date: Wed, 13 Jan 2021 23:07:59 +0100
Subject: [PATCH 30/50] docs: Write a HOW TO guide for using URL Reader

---
 docs/features/techdocs/how-to-guides.md | 54 +++++++++++++++++++++++++
 microsite/sidebars.json                 |  1 +
 mkdocs.yml                              |  1 +
 3 files changed, 56 insertions(+)
 create mode 100644 docs/features/techdocs/how-to-guides.md

diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md
new file mode 100644
index 0000000000..b32ff40589
--- /dev/null
+++ b/docs/features/techdocs/how-to-guides.md
@@ -0,0 +1,54 @@
+---
+id: how-to-guides
+title: TechDocs "HOW TO" guides
+sidebar_label: "HOW TO" guides
+description: TechDocs "HOW TO" guides related to TechDocs
+---
+
+## How to use URL Reader in TechDocs Prepare step?
+
+If TechDocs is configured to generate docs, it will first download the
+repository associated with the `backstage.io/techdocs-ref` annotation defined in
+the Entity's `catalog-info.yaml` file. This is also called the
+[Prepare](./concepts.md#techdocs-preparer) step.
+
+There are two kinds of preparers or two ways of downloading these source files
+
+- Preparer 1: Doing a `git clone` of the repository (also known as Common Git
+  Preparer)
+- Preparer 2: Downloading an archive.zip or equivalent of the repository (also
+  known as URL Reader)
+
+If `backstage.io/techdocs-ref` is equal to any of these -
+
+1. `github:https://githubhost.com/org/repo`
+2. `gitlab:https://gitlabhost.com/org/repo`
+3. `bitbucket:https://bitbuckethost.com/project/repo`
+4. `azure/api:https://azurehost.com/org/project`
+
+Then Common Git Preparer will be used i.e. a `git clone`. But the URL Reader is
+a much faster way to do this step. Convert the `backstage.io/techdocs-ref`
+values to the following -
+
+1. `url:https://githubhost.com/org/repo/tree/<branch_name>`
+2. `url:https://gitlabhost.com/org/repo/tree/<branch_name>`
+3. `url:https://bitbuckethost.com/project/repo/src/<branch_name>`
+4. `url:https://azurehost.com/organization/project/_git/repository`
+
+Note that you can also provide a path to a non-root directory inside the
+repository which contains the `docs/` directory.
+
+e.g.
+`url:https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend/examples/documented-component`
+
+### Why is URL Reader faster than a git clone?
+
+URL Reader uses the source code hosting provider to download a zip or tarball of
+the repository. The archive does not have any git history attached to it. Also
+it is a compressed file. Hence the file size is significantly smaller than how
+much data git clone has to transfer.
+
+Caveat: Currently TechDocs sites built using URL Reader will be cached for 30
+minutes which means they will not be re-built if new changes are made within 30
+minutes. This cache invalidation will be replaced by commit timestamp based
+implementation very soon.
diff --git a/microsite/sidebars.json b/microsite/sidebars.json
index 3d6417cc65..0dc4628c1a 100644
--- a/microsite/sidebars.json
+++ b/microsite/sidebars.json
@@ -83,6 +83,7 @@
           "features/techdocs/creating-and-publishing",
           "features/techdocs/configuration",
           "features/techdocs/using-cloud-storage",
+          "features/techdocs/how-to-guides",
           "features/techdocs/troubleshooting",
           "features/techdocs/faqs"
         ]
diff --git a/mkdocs.yml b/mkdocs.yml
index 29198963e3..c7ca02432b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -56,6 +56,7 @@ nav:
           - Creating and Publishing Documentation: 'features/techdocs/creating-and-publishing.md'
           - Configuration: 'features/techdocs/configuration.md'
           - Using Cloud Storage: 'features/techdocs/using-cloud-storage.md'
+          - HOW TO guides: 'features/techdocs/how-to-guides.md'
           - Troubleshooting: 'features/techdocs/troubleshooting.md'
           - FAQ: 'features/techdocs/FAQ.md'
       - Kubernetes:

From 22d2a523475b6e817cd221fc508171afa15a008c Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 14 Jan 2021 12:25:58 +0100
Subject: [PATCH 31/50] Apply suggestions from code review

Co-authored-by: Himanshu Mishra <himanshu@orkohunter.net>
---
 docs/plugins/composability.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/plugins/composability.md b/docs/plugins/composability.md
index e6f00d2374..5f1be7a561 100644
--- a/docs/plugins/composability.md
+++ b/docs/plugins/composability.md
@@ -1,8 +1,8 @@
 ---
 id: composability
 title: Composability System Migration
-description:
-  Documentation and migration instructions for new composability APIs.
+# prettier-ignore
+description: Documentation and migration instructions for new composability APIs.
 ---
 
 ## Summary
@@ -59,7 +59,7 @@ inspected, while our component data adds more structured access and simplifies
 evolution by allowing for multiple different versions of a piece of data to be
 used and interpreted at once.
 
-The initial use-cases for component data is support route and plugin discovery
+The initial use-case for component data is to support route and plugin discovery
 through elements in the app. Through this we allow for the React element tree in
 the app to be the source of truth, both for which plugins are used, as well as
 all top-level plugin routes in the app. The use of component data is not limited
@@ -254,8 +254,8 @@ const headerLinkRouteRef = createExternalRouteRef();
 ### Binding External Routes in the App
 
 The association of external routes is controlled by the app. Each
-`ExternalRouteRef` of a plugin should be<- bound to an actual `RouteRef`,
-usually from another plugin. The binding process happens once att app startup,
+`ExternalRouteRef` of a plugin should be bound to an actual `RouteRef`,
+usually from another plugin. The binding process happens once at app startup,
 and is then used through the lifetime of the app to help resolve concrete route
 paths.
 
@@ -517,15 +517,15 @@ It would be ported to this:
 ```tsx
 <EntityLayout>
   <EntityLayout.Route path="/" title="Overview">
-    <ComponentOverviewContent entity={entity} />}
+    <ComponentOverviewContent entity={entity} />
   </EntityLayout.Route>
 
   <EntityLayout.Route path="/sentry" title="Sentry">
-    <SentryRouter entity={entity} />}
+    <SentryRouter entity={entity} />
   </EntityLayout.Route>
 
   <EntityLayout.Route path="/kubernetes" title="Kubernetes">
-    <KubernetesRouter entity={entity} />}
+    <KubernetesRouter entity={entity} />
   </EntityLayout.Route>
 </EntityLayout>
 ```

From 151e36504020a747a1e3072781cf2237888c7e60 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 14 Jan 2021 12:53:25 +0100
Subject: [PATCH 32/50] docs/composability: ran prettier + added to mkdocs.yml

---
 docs/plugins/composability.md | 7 +++----
 mkdocs.yml                    | 1 +
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/plugins/composability.md b/docs/plugins/composability.md
index 5f1be7a561..c23ab2882d 100644
--- a/docs/plugins/composability.md
+++ b/docs/plugins/composability.md
@@ -254,10 +254,9 @@ const headerLinkRouteRef = createExternalRouteRef();
 ### Binding External Routes in the App
 
 The association of external routes is controlled by the app. Each
-`ExternalRouteRef` of a plugin should be bound to an actual `RouteRef`,
-usually from another plugin. The binding process happens once at app startup,
-and is then used through the lifetime of the app to help resolve concrete route
-paths.
+`ExternalRouteRef` of a plugin should be bound to an actual `RouteRef`, usually
+from another plugin. The binding process happens once at app startup, and is
+then used through the lifetime of the app to help resolve concrete route paths.
 
 Using the above example of the `BarPage` linking to the `FooPage`, we might do
 something like this in the app:
diff --git a/mkdocs.yml b/mkdocs.yml
index 29198963e3..105ad721d5 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -66,6 +66,7 @@ nav:
       - Creating a new plugin: 'plugins/create-a-plugin.md'
       - Developing a plugin: 'plugins/plugin-development.md'
       - Structure of a plugin: 'plugins/structure-of-a-plugin.md'
+      - Composability System Migration: 'plugins/composability.md'
       - Backends and APIs:
           - Proxying: 'plugins/proxying.md'
           - Backstage backend plugin: 'plugins/backend-plugin.md'

From 38545afbfa36606d964847eba0929dcf6f591b8a Mon Sep 17 00:00:00 2001
From: Adam Harvey <adam.harvey@dxc.com>
Date: Thu, 14 Jan 2021 10:30:55 -0500
Subject: [PATCH 33/50] Add Bad Request test

---
 .../src/service/KubernetesFetcher.test.ts     | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/plugins/kubernetes-backend/src/service/KubernetesFetcher.test.ts b/plugins/kubernetes-backend/src/service/KubernetesFetcher.test.ts
index 29233cf7fd..8d29439539 100644
--- a/plugins/kubernetes-backend/src/service/KubernetesFetcher.test.ts
+++ b/plugins/kubernetes-backend/src/service/KubernetesFetcher.test.ts
@@ -197,6 +197,27 @@ describe('KubernetesClientProvider', () => {
   });
   // they're in testErrorResponse
   // eslint-disable-next-line jest/expect-expect
+  it('should return pods, bad request error', async () => {
+    await testErrorResponse(
+      {
+        response: {
+          statusCode: 400,
+          request: {
+            uri: {
+              pathname: '/some/path',
+            },
+          },
+        },
+      },
+      {
+        errorType: 'BAD_REQUEST',
+        resourcePath: '/some/path',
+        statusCode: 400,
+      },
+    );
+  });
+  // they're in testErrorResponse
+  // eslint-disable-next-line jest/expect-expect
   it('should return pods, unauthorized error', async () => {
     await testErrorResponse(
       {

From 93be0f55e32d5aadb2ac5daa5b64adb4d882879d Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 14 Jan 2021 16:34:59 +0100
Subject: [PATCH 34/50] docs/composability: fooRootRouteRef -> fooPageRouteRef

---
 docs/plugins/composability.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/plugins/composability.md b/docs/plugins/composability.md
index c23ab2882d..207540b989 100644
--- a/docs/plugins/composability.md
+++ b/docs/plugins/composability.md
@@ -139,7 +139,7 @@ a component:
 export const FooPage = plugin.provide(
   createRoutableExtension({
     component: () => import('./components/FooPage').then(m => m.FooPage),
-    mountPoint: fooRouteRef,
+    mountPoint: fooPageRouteRef,
   }),
 );
 ```
@@ -213,9 +213,9 @@ const appRoutes = (
 We'll assume that `FooPage` and `BarPage` are routable extensions, exported by
 the `fooPlugin` and `barPlugin` respectively. Since the `FooPage` is a routable
 extension it has a `RouteRef` assigned as its mount point, which we'll refer to
-as `fooRootRouteRef`.
+as `fooPageRouteRef`.
 
-Given the above example, the `fooRootRouteRef` will be associated with the
+Given the above example, the `fooPageRouteRef` will be associated with the
 `'/foo'` route. The path is no longer accessible via the `path` property of the
 `RouteRef` though, as the routing structure is tied to the app's react tree. We
 instead use the new `useRouteRef` hook if we want to create a concrete link to
@@ -225,14 +225,14 @@ like this:
 
 ```tsx
 const MyComponent = () => {
-  const fooRoute = useRouteRef(fooRouteRef);
+  const fooRoute = useRouteRef(fooPageRouteRef);
   return <a href={fooRoute()}>Link to Foo</a>;
 };
 ```
 
 Now let's assume that we want to link from the `BarPage` to the `FooPage`.
 Before the introduction of the new composability system, we would do this by
-importing the `fooRootRouteRef` from the `fooPlugin`. This created an
+importing the `fooPageRouteRef` from the `fooPlugin`. This created an
 unnecessary dependency on the plugin, and also provided little flexibility in
 allowing the app to tie plugins together, with the links instead being dictated
 by the plugins themselves. To solve this, we introduce `ExternalRouteRef`s. Much
@@ -285,7 +285,7 @@ like this:
 // In foo-plugin
 export const fooPlugin = createPlugin({
   routes: {
-    root: fooRootRouteRef,
+    root: fooPageRouteRef,
   },
   ...
 })

From 68cf50c52372d1ce4964465abb108f9ae96285ee Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 14 Jan 2021 16:36:41 +0100
Subject: [PATCH 35/50] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/plugins/composability.md | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/docs/plugins/composability.md b/docs/plugins/composability.md
index 207540b989..a496217875 100644
--- a/docs/plugins/composability.md
+++ b/docs/plugins/composability.md
@@ -10,7 +10,7 @@ description: Documentation and migration instructions for new composability APIs
 This page describes the new composability system that was recently introduced in
 Backstage, and it does so from the perspective of the existing patterns and
 APIs. As the new system is solidified and existing code is ported, this page
-will removed and replaced with a more direct description of the composability
+will be removed and replaced with a more direct description of the composability
 system. For now, the primary purpose of this documentation is to aid in the
 migration of existing plugins, but it does cover the migration of apps as well.
 
@@ -232,7 +232,7 @@ const MyComponent = () => {
 
 Now let's assume that we want to link from the `BarPage` to the `FooPage`.
 Before the introduction of the new composability system, we would do this by
-importing the `fooPageRouteRef` from the `fooPlugin`. This created an
+importing the `fooPageRouteRef` exported by the `fooPlugin`. This created an
 unnecessary dependency on the plugin, and also provided little flexibility in
 allowing the app to tie plugins together, with the links instead being dictated
 by the plugins themselves. To solve this, we introduce `ExternalRouteRef`s. Much
@@ -272,7 +272,8 @@ createApp({
 ```
 
 Given the above binding, using `useRouteRef(headerLinkRouteRef)` within the
-`barPlugin` will let us create a link whatever path the `FooPage` is mounted at.
+`barPlugin` will let us create a link to whatever path the `FooPage` is mounted
+at.
 
 Note that we are not importing and using the `RouteRef`s directly in the app,
 and instead rely on the plugin instance to access routes of the plugins. This is
@@ -302,7 +303,7 @@ export const barPlugin = createPlugin({
 Also note that you almost always want to create the route references themselves
 in a different file than the one that creates the plugin instance, for example a
 top-level `routes.ts`. This is to avoid circular imports when you use the route
-references from other parts of the app.
+references from other parts of the same plugin.
 
 ### Parameterized Routes
 
@@ -347,11 +348,11 @@ entity. A `switch` or `if` / `else if` chain is then used to select what
 children should be rendered based on information in the entity.
 
 This pattern will no longer work with the new composability system, and in
-general is very difficult to build any form declarative model around, as it
+general is very difficult to build any form of declarative model around, as it
 depends on runtime execution. To help replace existing code, a new
 `EntitySwitch` component has been added to the `@backstage/catalog` plugin,
-which grabs the selected entity from context, and selects at most one element to
-render using a list of `EntitySwitch.Case`s children.
+which grabs the selected entity from a context, and selects at most one element
+to render using a list of `EntitySwitch.Case` children.
 
 For example, if you want all entities of kind `"Template"` to be rendered with a
 `MyTemplate` component, and all other entities to be rendered with a `MyOther`
@@ -530,8 +531,8 @@ It would be ported to this:
 ```
 
 In addition to the renaming, the `element` prop has been moved to `children`.
-Also note that the `/*` suffix has been remove from the `"/kubernetes"` path, as
-it's now added automatically.
+Also note that the `/*` suffix has been removed from the `"/kubernetes"` path,
+as it's now added automatically.
 
 Usage of the `EntityLayout` component is required to be able to properly
 discover routes, and so it is required to apply this change before you can start

From d54857099dfcb49e2aa3664cd1efb96c611bbfcb Mon Sep 17 00:00:00 2001
From: Adam Harvey <adam.harvey@dxc.com>
Date: Thu, 14 Jan 2021 10:52:53 -0500
Subject: [PATCH 36/50] Add changeset

---
 .changeset/bright-icons-repair.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/bright-icons-repair.md

diff --git a/.changeset/bright-icons-repair.md b/.changeset/bright-icons-repair.md
new file mode 100644
index 0000000000..8c3f43403a
--- /dev/null
+++ b/.changeset/bright-icons-repair.md
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-kubernetes-backend': patch
+---
+
+Support HTTP 400 Bad Request from Kubernetes API

From be1e8af024e21f96b8124c4f25e54258bd7b8c75 Mon Sep 17 00:00:00 2001
From: Adam Harvey <adam.harvey@dxc.com>
Date: Thu, 14 Jan 2021 22:17:12 -0500
Subject: [PATCH 37/50] Reduce log noise

---
 plugins/catalog-backend/src/ingestion/HigherOrderOperations.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/catalog-backend/src/ingestion/HigherOrderOperations.ts b/plugins/catalog-backend/src/ingestion/HigherOrderOperations.ts
index b7e9c48fe5..ba97232810 100644
--- a/plugins/catalog-backend/src/ingestion/HigherOrderOperations.ts
+++ b/plugins/catalog-backend/src/ingestion/HigherOrderOperations.ts
@@ -186,7 +186,7 @@ export class HigherOrderOperations implements HigherOrderOperation {
       throw e;
     }
 
-    this.logger.info(`Posting update success markers`);
+    this.logger.debug(`Posting update success markers`);
 
     await this.locationsCatalog.logUpdateSuccess(
       location.id,

From ad838c02f73f7dcec230988f96472a89467931eb Mon Sep 17 00:00:00 2001
From: Adam Harvey <adam.harvey@dxc.com>
Date: Thu, 14 Jan 2021 22:25:30 -0500
Subject: [PATCH 38/50] Add changeset

---
 .changeset/spotty-moons-tap.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/spotty-moons-tap.md

diff --git a/.changeset/spotty-moons-tap.md b/.changeset/spotty-moons-tap.md
new file mode 100644
index 0000000000..facb76a296
--- /dev/null
+++ b/.changeset/spotty-moons-tap.md
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Reduce log noise on locations refresh

From a594a725767dd9a9c4ebe0fd282a07c023eaf23b Mon Sep 17 00:00:00 2001
From: Himanshu Mishra <himanshu@orkohunter.net>
Date: Fri, 15 Jan 2021 09:26:26 +0100
Subject: [PATCH 39/50] techdocs-common: Allow techdocs-cli to import in a
 non-backstage environment

techdocs-common has a dependency on @backstage/plugin-techdocs-backend. This prohibits techdocs-cli to import it and generate/publish docs on a CI/CD environment to an external storage
---
 .changeset/techdocs-mean-items-behave.md      |  5 ++++
 .../src/stages/publish/local.ts               | 28 ++++++++++++++-----
 2 files changed, 26 insertions(+), 7 deletions(-)
 create mode 100644 .changeset/techdocs-mean-items-behave.md

diff --git a/.changeset/techdocs-mean-items-behave.md b/.changeset/techdocs-mean-items-behave.md
new file mode 100644
index 0000000000..77679c39d4
--- /dev/null
+++ b/.changeset/techdocs-mean-items-behave.md
@@ -0,0 +1,5 @@
+---
+'@backstage/techdocs-common': patch
+---
+
+@backstage/techdocs-common can now be imported in an environment without @backstage/plugin-techdocs-backend being installed.
diff --git a/packages/techdocs-common/src/stages/publish/local.ts b/packages/techdocs-common/src/stages/publish/local.ts
index 2739940530..de670cfba5 100644
--- a/packages/techdocs-common/src/stages/publish/local.ts
+++ b/packages/techdocs-common/src/stages/publish/local.ts
@@ -16,6 +16,8 @@
 import fetch from 'cross-fetch';
 import express from 'express';
 import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
 import { Logger } from 'winston';
 import { Entity, EntityName } from '@backstage/catalog-model';
 import {
@@ -25,10 +27,20 @@ import {
 import { Config } from '@backstage/config';
 import { PublisherBase, PublishRequest, PublishResponse } from './types';
 
-const staticDocsDir = resolvePackagePath(
-  '@backstage/plugin-techdocs-backend',
-  'static/docs',
-);
+// TODO: Use a more persistent storage than node_modules or /tmp directory.
+// Make it configurable with techdocs.publisher.local.publishDirectory
+let staticDocsDir = '';
+try {
+  staticDocsDir = resolvePackagePath(
+    '@backstage/plugin-techdocs-backend',
+    'static/docs',
+  );
+} catch (err) {
+  // This will most probably never be used.
+  // The try/catch is introduced so that techdocs-cli can import @backstage/techdocs-common
+  // on CI/CD without installing techdocs backend plugin.
+  staticDocsDir = os.tmpdir();
+}
 
 /**
  * Local publisher which uses the local filesystem to store the generated static files. It uses a directory
@@ -39,6 +51,9 @@ export class LocalPublish implements PublisherBase {
   private readonly logger: Logger;
   private readonly discovery: PluginEndpointDiscovery;
 
+  // TODO: Use a static fromConfig method to create a LocalPublish instance, similar to aws/gcs publishers.
+  // Move the logic of setting staticDocsDir based on config over to fromConfig,
+  // and set the value as a class parameter.
   constructor(
     config: Config,
     logger: Logger,
@@ -52,9 +67,8 @@ export class LocalPublish implements PublisherBase {
   publish({ entity, directory }: PublishRequest): Promise<PublishResponse> {
     const entityNamespace = entity.metadata.namespace ?? 'default';
 
-    const publishDir = resolvePackagePath(
-      '@backstage/plugin-techdocs-backend',
-      'static/docs',
+    const publishDir = path.join(
+      staticDocsDir,
       entityNamespace,
       entity.kind,
       entity.metadata.name,

From 057cb8e84fe235dcf00e64f733e2d948032ef83f Mon Sep 17 00:00:00 2001
From: Emma Indal <emmai@spotify.com>
Date: Fri, 15 Jan 2021 10:45:39 +0100
Subject: [PATCH 40/50] Backstage Glossary Documentation (#4073)

* add Backstage Glossary documentation

* Update docs/glossary.md

Co-authored-by: Himanshu Mishra <himanshu@orkohunter.net>

* Update docs/glossary.md

Co-authored-by: Adam Harvey <adam.harvey@dxc.com>

* Update docs/glossary.md

Co-authored-by: Adam Harvey <adam.harvey@dxc.com>

* updates from feedback

Co-authored-by: Himanshu Mishra <himanshu@orkohunter.net>
Co-authored-by: Adam Harvey <adam.harvey@dxc.com>
---
 docs/glossary.md        | 21 +++++++++++++++++++++
 microsite/sidebars.json |  1 +
 mkdocs.yml              |  1 +
 3 files changed, 23 insertions(+)
 create mode 100644 docs/glossary.md

diff --git a/docs/glossary.md b/docs/glossary.md
new file mode 100644
index 0000000000..dc67b2aae2
--- /dev/null
+++ b/docs/glossary.md
@@ -0,0 +1,21 @@
+---
+id: Glossary
+title: Backstage Glossary
+# prettier-ignore
+description: List of all the terms, abbreviations, and phrases used in Backstage, together with their explanations.
+---
+
+The Backstage Glossary lists all the terms, abbreviations, and phrases used in
+Backstage, together with their explanations. We encourage you to use the
+terminology below for clarity and consistency when discussing Backstage.
+
+### Backstage User Profiles
+
+There are three main user profiles for Backstage: the integrator, the
+contributor, and the software engineer.
+
+| Term              | Explanation                                                                                                                                                                                                                                                                            |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Integrator        | The **integrator** hosts the Backstage app and configures which plugins are available to use in the app.                                                                                                                                                                               |
+| Contributor       | The **contributor** adds functionality to the app by writing plugins.                                                                                                                                                                                                                  |
+| Software Engineer | The **software engineer** uses the app's functionality and interacts with its plugins. In practice, this profile covers the various roles that help deliver software, from the Software Engineer themselves, to Designers, Data Scientists, Product Owners, Engineering Managers, etc. |
diff --git a/microsite/sidebars.json b/microsite/sidebars.json
index 3d6417cc65..07245e75e5 100644
--- a/microsite/sidebars.json
+++ b/microsite/sidebars.json
@@ -176,6 +176,7 @@
     ],
     "Contribute": ["../CONTRIBUTING"],
     "Support": ["support/support", "support/project-structure"],
+    "Glossary": ["glossary"],
     "FAQ": ["FAQ"]
   }
 }
diff --git a/mkdocs.yml b/mkdocs.yml
index 29198963e3..fce5fc1a42 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -117,4 +117,5 @@ nav:
   - Support:
       - 'support/support.md'
       - 'support/project-structure.md'
+  - Glossary: glossary.md
   - FAQ: FAQ.md

From be2f9d8049f1accf14d4412f7ecf36b19f6d1580 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Fri, 15 Jan 2021 11:43:16 +0100
Subject: [PATCH 41/50] microsite: fix display of summary elements

---
 microsite/static/css/custom.css | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/microsite/static/css/custom.css b/microsite/static/css/custom.css
index 46b2aa3470..01bb3c89eb 100644
--- a/microsite/static/css/custom.css
+++ b/microsite/static/css/custom.css
@@ -48,6 +48,11 @@ h6 {
   color: $textColor;
 }
 
+summary {
+  color: $textColor;
+  cursor: pointer;
+}
+
 h2:hover .hash-link {
   opacity: 1;
 }

From ac7be581a1c67177caaf89a3b5b3dad6c6b6666c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= <freben@gmail.com>
Date: Fri, 15 Jan 2021 12:03:50 +0100
Subject: [PATCH 42/50] catalog-backend: Refuse to remove the bootstrap
 location

---
 .changeset/orange-avocados-work.md             |  5 +++++
 .../src/database/CommonDatabase.test.ts        | 16 ++++++++++++++++
 .../src/database/CommonDatabase.ts             | 18 ++++++++++++------
 3 files changed, 33 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/orange-avocados-work.md

diff --git a/.changeset/orange-avocados-work.md b/.changeset/orange-avocados-work.md
new file mode 100644
index 0000000000..a1f3597302
--- /dev/null
+++ b/.changeset/orange-avocados-work.md
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Refuse to remove the bootstrap location
diff --git a/plugins/catalog-backend/src/database/CommonDatabase.test.ts b/plugins/catalog-backend/src/database/CommonDatabase.test.ts
index 130ed41eb1..b319bb832d 100644
--- a/plugins/catalog-backend/src/database/CommonDatabase.test.ts
+++ b/plugins/catalog-backend/src/database/CommonDatabase.test.ts
@@ -137,6 +137,22 @@ describe('CommonDatabase', () => {
     await expect(db.location(location.id)).rejects.toThrow(/Found no location/);
   });
 
+  it('refuses to remove the bootstrap location', async () => {
+    const input: Location = {
+      id: 'dd12620d-0436-422f-93bd-929aa0788123',
+      type: 'bootstrap',
+      target: 'bootstrap',
+    };
+
+    const output = await db.transaction(
+      async tx => await db.addLocation(tx, input),
+    );
+
+    await expect(
+      db.transaction(async tx => await db.removeLocation(tx, output.id)),
+    ).rejects.toThrow(ConflictError);
+  });
+
   describe('addEntities', () => {
     it('happy path: adds entities to empty database', async () => {
       const result = await db.transaction(tx =>
diff --git a/plugins/catalog-backend/src/database/CommonDatabase.ts b/plugins/catalog-backend/src/database/CommonDatabase.ts
index d641cbb7b6..2edc0ca5b8 100644
--- a/plugins/catalog-backend/src/database/CommonDatabase.ts
+++ b/plugins/catalog-backend/src/database/CommonDatabase.ts
@@ -330,15 +330,21 @@ export class CommonDatabase implements Database {
   async removeLocation(txOpaque: Transaction, id: string): Promise<void> {
     const tx = txOpaque as Knex.Transaction<any, any>;
 
+    const locations = await tx<DbLocationsRow>('locations')
+      .where({ id })
+      .select();
+    if (!locations.length) {
+      throw new NotFoundError(`Found no location with ID ${id}`);
+    }
+
+    if (locations[0].type === 'bootstrap') {
+      throw new ConflictError('You may not delete the bootstrap location.');
+    }
+
     await tx<DbEntitiesRow>('entities')
       .where({ location_id: id })
       .update({ location_id: null });
-
-    const result = await tx<DbLocationsRow>('locations').where({ id }).del();
-
-    if (!result) {
-      throw new NotFoundError(`Found no location with ID ${id}`);
-    }
+    await tx<DbLocationsRow>('locations').where({ id }).del();
   }
 
   async location(id: string): Promise<DbLocationsRowWithStatus> {

From 8c2437c15a071137ef26888a305f1d7acd7b0e39 Mon Sep 17 00:00:00 2001
From: Himanshu Mishra <himanshu@orkohunter.net>
Date: Fri, 15 Jan 2021 12:41:52 +0100
Subject: [PATCH 43/50] Fix invalid changeset file format

I guess changesets are not tracked if they are not an `.md` file in the `.changeset` directory. @backstage/silver-lining
---
 ...less-coins-pretend => cost-insights-careless-coins-pretend.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename .changeset/{cost-insights-careless-coins-pretend => cost-insights-careless-coins-pretend.md} (100%)

diff --git a/.changeset/cost-insights-careless-coins-pretend b/.changeset/cost-insights-careless-coins-pretend.md
similarity index 100%
rename from .changeset/cost-insights-careless-coins-pretend
rename to .changeset/cost-insights-careless-coins-pretend.md

From f9ba00a1cad3f3cc5f73a815ea7d1f1e795f5c6a Mon Sep 17 00:00:00 2001
From: Oliver Sand <oliver.sand@sda-se.com>
Date: Fri, 15 Jan 2021 13:34:04 +0100
Subject: [PATCH 44/50] Update @azure/msal-node to 1.0.0-beta.3

The new version introduced a breaking change and requires manual changes.
---
 .changeset/wild-cats-end.md                   |  5 ++++
 plugins/catalog-backend/package.json          |  2 +-
 .../processors/microsoftGraph/client.ts       |  4 +++
 yarn.lock                                     | 27 +++++++++----------
 4 files changed, 23 insertions(+), 15 deletions(-)
 create mode 100644 .changeset/wild-cats-end.md

diff --git a/.changeset/wild-cats-end.md b/.changeset/wild-cats-end.md
new file mode 100644
index 0000000000..d2c9e6f245
--- /dev/null
+++ b/.changeset/wild-cats-end.md
@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend': patch
+---
+
+Update the @azure/msal-node dependency to 1.0.0-beta.3.
diff --git a/plugins/catalog-backend/package.json b/plugins/catalog-backend/package.json
index 0ce2e8d37a..e6b6713e20 100644
--- a/plugins/catalog-backend/package.json
+++ b/plugins/catalog-backend/package.json
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.2.0",
-    "@azure/msal-node": "^1.0.0-alpha.8",
+    "@azure/msal-node": "^1.0.0-beta.3",
     "@backstage/backend-common": "^0.4.3",
     "@backstage/catalog-model": "^0.6.1",
     "@backstage/config": "^0.1.2",
diff --git a/plugins/catalog-backend/src/ingestion/processors/microsoftGraph/client.ts b/plugins/catalog-backend/src/ingestion/processors/microsoftGraph/client.ts
index bdb5918b2f..3dfc58e773 100644
--- a/plugins/catalog-backend/src/ingestion/processors/microsoftGraph/client.ts
+++ b/plugins/catalog-backend/src/ingestion/processors/microsoftGraph/client.ts
@@ -96,6 +96,10 @@ export class MicrosoftGraphClient {
       scopes: ['https://graph.microsoft.com/.default'],
     });
 
+    if (!token) {
+      throw new Error('Error while requesting token for Microsoft Graph');
+    }
+
     return await fetch(url, {
       headers: {
         Authorization: `Bearer ${token.accessToken}`,
diff --git a/yarn.lock b/yarn.lock
index 955b6305c3..7fdc2c3a62 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -879,21 +879,20 @@
   dependencies:
     tslib "^1.8.0"
 
-"@azure/msal-common@^1.6.2":
-  version "1.6.2"
-  resolved "https://registry.npmjs.org/@azure/msal-common/-/msal-common-1.6.2.tgz#91f3732866d727e20f1e142e6e88a981268fbff2"
-  integrity sha512-GShzp1q7Ld8SwYiDEjQZ9PmFOY4x+2stE86maiguylE9/d/c2muqKjc8aepmEqyjbV7o/omDvEf2Sr9QcIqkSA==
+"@azure/msal-common@^2.1.0":
+  version "2.1.0"
+  resolved "https://registry.npmjs.org/@azure/msal-common/-/msal-common-2.1.0.tgz#a4bc17e254d6ec524016f13267947dd4ff4a624d"
+  integrity sha512-Y1Id+jG59S3eY2ZQQtUA/lxwbRcgjcWaiib9YX+SwV3zeRauKfEiZT7l3z+lwV+T+Sst20F6l1mJsfQcfE7CEQ==
   dependencies:
     debug "^4.1.1"
 
-"@azure/msal-node@^1.0.0-alpha.8":
-  version "1.0.0-alpha.12"
-  resolved "https://registry.npmjs.org/@azure/msal-node/-/msal-node-1.0.0-alpha.12.tgz#09d8d52f5cea90b133c3d48fe4ec477693040c91"
-  integrity sha512-uGLOJRWiEhfJIrTv/lwdm4RxQFm++00h83zNgDn0O3NkXlzAoCCq9QFYW84PjMR/Q2PUvVy7uW+6yKL/Nq3gBA==
+"@azure/msal-node@^1.0.0-beta.3":
+  version "1.0.0-beta.3"
+  resolved "https://registry.npmjs.org/@azure/msal-node/-/msal-node-1.0.0-beta.3.tgz#c84c7948028b39e48b901f5fac35bdedcbc8772e"
+  integrity sha512-/KfYRfrsOIrZONvo/0Vi5umuqbPBtCWNtmRvkse64uI0C4CP/W4WXwRD42VMws/8LtKvr1I5rYlYgFzt5zDz/A==
   dependencies:
-    "@azure/msal-common" "^1.6.2"
-    axios "^0.19.2"
-    debug "^4.1.1"
+    "@azure/msal-common" "^2.1.0"
+    axios "^0.21.1"
     jsonwebtoken "^8.5.1"
     uuid "^8.3.0"
 
@@ -2436,7 +2435,7 @@
     to-fast-properties "^2.0.0"
 
 "@backstage/catalog-model@^0.2.0":
-  version "0.6.0"
+  version "0.6.1"
   dependencies:
     "@backstage/config" "^0.1.2"
     "@types/json-schema" "^7.0.5"
@@ -2447,7 +2446,7 @@
     yup "^0.29.3"
 
 "@backstage/catalog-model@^0.3.0":
-  version "0.6.0"
+  version "0.6.1"
   dependencies:
     "@backstage/config" "^0.1.2"
     "@types/json-schema" "^7.0.5"
@@ -2458,7 +2457,7 @@
     yup "^0.29.3"
 
 "@backstage/core@^0.3.0":
-  version "0.4.3"
+  version "0.4.4"
   dependencies:
     "@backstage/config" "^0.1.2"
     "@backstage/core-api" "^0.2.8"

From d1ccd52a9d58d1dcc312a8738fa3a1b79cded8c1 Mon Sep 17 00:00:00 2001
From: Johan Haals <johan.haals@gmail.com>
Date: Fri, 15 Jan 2021 16:17:11 +0100
Subject: [PATCH 45/50] cli: Append credentials to create-github-app output
 name

---
 packages/cli/src/commands/create-github-app/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/cli/src/commands/create-github-app/index.ts b/packages/cli/src/commands/create-github-app/index.ts
index b8d232674e..2dd0d31232 100644
--- a/packages/cli/src/commands/create-github-app/index.ts
+++ b/packages/cli/src/commands/create-github-app/index.ts
@@ -26,7 +26,7 @@ import { GithubCreateAppServer } from './GithubCreateAppServer';
 export default async (org: string) => {
   const { slug, name, ...config } = await GithubCreateAppServer.run({ org });
 
-  const fileName = `github-app-${slug}.yaml`;
+  const fileName = `github-app-${slug}-credentials.yaml`;
   const content = `# Name: ${name}\n${stringifyYaml(config)}`;
   await fs.writeFile(paths.resolveTargetRoot(fileName), content);
   console.log(`GitHub App configuration written to ${chalk.cyan(fileName)}`);

From c48119248846e45d572e3065ae2ad0b78e46572f Mon Sep 17 00:00:00 2001
From: Johan Haals <johan.haals@gmail.com>
Date: Fri, 15 Jan 2021 16:25:29 +0100
Subject: [PATCH 46/50] gitignore: Ignore *-credentials.yaml

---
 .gitignore                                               | 3 +++
 packages/create-app/templates/default-app/.gitignore.hbs | 5 ++++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 3334bf956d..57ad74c5cc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -130,3 +130,6 @@ site
 
 # Local configuration files
 *.local.yaml
+
+# Sensitive credentials
+*-credentials.yaml
diff --git a/packages/create-app/templates/default-app/.gitignore.hbs b/packages/create-app/templates/default-app/.gitignore.hbs
index 5f5cc739f4..4adebc5adc 100644
--- a/packages/create-app/templates/default-app/.gitignore.hbs
+++ b/packages/create-app/templates/default-app/.gitignore.hbs
@@ -30,4 +30,7 @@ dist-types
 site
 
 # Local configuration files
-*.local.yaml
\ No newline at end of file
+*.local.yaml
+
+# Sensitive credentials
+*-credentials.yaml

From b604a9d41192b643436f36283b8fdd43235f14b5 Mon Sep 17 00:00:00 2001
From: Johan Haals <johan.haals@gmail.com>
Date: Fri, 15 Jan 2021 16:35:06 +0100
Subject: [PATCH 47/50] Add changeset

---
 .changeset/loud-kids-dance.md | 8 ++++++++
 1 file changed, 8 insertions(+)
 create mode 100644 .changeset/loud-kids-dance.md

diff --git a/.changeset/loud-kids-dance.md b/.changeset/loud-kids-dance.md
new file mode 100644
index 0000000000..035e038f58
--- /dev/null
+++ b/.changeset/loud-kids-dance.md
@@ -0,0 +1,8 @@
+---
+'@backstage/cli': patch
+'@backstage/create-app': patch
+---
+
+Append `-credentials.yaml` to credentials file generated by `backstage-cli create-github-app`.
+
+Add `*-credentials.yaml` to gitignore to prevent accidental commits.

From 7d2a390a4f27107c23eabdecc95bfee7a8286a39 Mon Sep 17 00:00:00 2001
From: Johan Haals <johan.haals@gmail.com>
Date: Fri, 15 Jan 2021 17:21:12 +0100
Subject: [PATCH 48/50] Warn user about sensitive credentials

---
 .changeset/loud-kids-dance.md                        | 5 +----
 packages/cli/src/commands/create-github-app/index.ts | 5 +++++
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/.changeset/loud-kids-dance.md b/.changeset/loud-kids-dance.md
index 035e038f58..4fd32ac348 100644
--- a/.changeset/loud-kids-dance.md
+++ b/.changeset/loud-kids-dance.md
@@ -1,8 +1,5 @@
 ---
 '@backstage/cli': patch
-'@backstage/create-app': patch
 ---
 
-Append `-credentials.yaml` to credentials file generated by `backstage-cli create-github-app`.
-
-Add `*-credentials.yaml` to gitignore to prevent accidental commits.
+Append `-credentials.yaml` to credentials file generated by `backstage-cli create-github-app` and display warning about sensitive contents.
diff --git a/packages/cli/src/commands/create-github-app/index.ts b/packages/cli/src/commands/create-github-app/index.ts
index 2dd0d31232..cd9e8dbe09 100644
--- a/packages/cli/src/commands/create-github-app/index.ts
+++ b/packages/cli/src/commands/create-github-app/index.ts
@@ -30,5 +30,10 @@ export default async (org: string) => {
   const content = `# Name: ${name}\n${stringifyYaml(config)}`;
   await fs.writeFile(paths.resolveTargetRoot(fileName), content);
   console.log(`GitHub App configuration written to ${chalk.cyan(fileName)}`);
+  console.log(
+    chalk.yellow(
+      'This file contains sensitive credentials, it should not be committed to version control and handled with care!',
+    ),
+  );
   // TODO: log instructions on how to use the newly created app configuration.
 };

From 92dbbcedd760bbab615bf5a2fabf4d988e4dc42b Mon Sep 17 00:00:00 2001
From: Johan Haals <johan.haals@gmail.com>
Date: Fri, 15 Jan 2021 17:21:44 +0100
Subject: [PATCH 49/50] Add changeset for create-app

---
 .changeset/spoon-fork.md | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 .changeset/spoon-fork.md

diff --git a/.changeset/spoon-fork.md b/.changeset/spoon-fork.md
new file mode 100644
index 0000000000..a9d5e42237
--- /dev/null
+++ b/.changeset/spoon-fork.md
@@ -0,0 +1,11 @@
+---
+'@backstage/create-app': patch
+---
+
+Add `*-credentials.yaml` to gitignore to prevent accidental commits of sensitive credential information.
+
+To apply this change to an existing installation, add this line to your `.gitignore`
+
+```gitignore
+*-credentials.yaml
+```

From d69d5d5ca8018f8efa8ee0f6414dab4107508d4f Mon Sep 17 00:00:00 2001
From: Johan Haals <johan.haals@gmail.com>
Date: Fri, 15 Jan 2021 17:25:33 +0100
Subject: [PATCH 50/50] Add comment to changeset

---
 .changeset/spoon-fork.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.changeset/spoon-fork.md b/.changeset/spoon-fork.md
index a9d5e42237..5b8620f94e 100644
--- a/.changeset/spoon-fork.md
+++ b/.changeset/spoon-fork.md
@@ -4,8 +4,9 @@
 
 Add `*-credentials.yaml` to gitignore to prevent accidental commits of sensitive credential information.
 
-To apply this change to an existing installation, add this line to your `.gitignore`
+To apply this change to an existing installation, add these lines to your `.gitignore`
 
 ```gitignore
+# Sensitive credentials
 *-credentials.yaml
 ```