From 98bad1b7d881e177fabf384308aad78970f6ce3c Mon Sep 17 00:00:00 2001
From: Nataliya Issayeva <nissayeva@users.noreply.github.com>
Date: Tue, 16 Nov 2021 10:30:59 -0800
Subject: [PATCH] Update changeset and docs

Signed-off-by: Nataliya Issayeva <nissayeva@users.noreply.github.com>
---
 .changeset/odd-flowers-hope.md          | 86 ++++++++++++++++++++++++-
 docs/features/search/getting-started.md | 16 ++++-
 docs/features/search/how-to-guides.md   |  3 +-
 3 files changed, 98 insertions(+), 7 deletions(-)

diff --git a/.changeset/odd-flowers-hope.md b/.changeset/odd-flowers-hope.md
index d66b59c5ca..c76f1b8287 100644
--- a/.changeset/odd-flowers-hope.md
+++ b/.changeset/odd-flowers-hope.md
@@ -2,8 +2,88 @@
 'example-backend': patch
 '@backstage/backend-common': patch
 '@backstage/create-app': patch
-'@backstage/plugin-catalog-backend': patch
-'@backstage/plugin-techdocs-backend': patch
+'@backstage/plugin-catalog-backend': minor
+'@backstage/plugin-techdocs-backend': minor
 ---
 
-Create a TokenManager interface and ServerTokenManager implementation to generate and validate server tokens for authenticated backend-to-backend API requests
+Create a TokenManager interface and ServerTokenManager implementation to generate and validate server tokens for authenticated backend-to-backend API requests.
+
+**BREAKING** `DefaultCatalogCollator` and `DefaultTechDocsCollator` now require a `tokenManager` to be passed in the `options` argument.
+
+In your backend, update the `PluginEnvironment` to include a `tokenManager`:
+
+```diff
+// packages/backend/src/types.ts
+
+...
+import {
+  ...
++ TokenManager,
+} from '@backstage/backend-common';
+
+export type PluginEnvironment = {
+  ...
++ tokenManager: TokenManager;
+};
+```
+
+Then, create a `ServerTokenManager`. This can either be a `noop` that requires no secret and validates all requests by default, or one that uses a secret from your `app-config.yaml` to generate and validate tokens.
+
+```diff
+// packages/backend/src/index.ts
+
+...
+import {
+  ...
++ ServerTokenManager,
+} from '@backstage/backend-common';
+...
+
+function makeCreateEnv(config: Config) {
+  ...
+  // CHOOSE ONE
+  // TokenManager not requiring a secret
++ const tokenManager = ServerTokenManager.noop();
+  // OR TokenManager requiring a secret
++ const tokenManager = ServerTokenManager.fromConfig(config);
+
+  ...
+  return (plugin: string): PluginEnvironment => {
+    ...
+-   return { logger, cache, database, config, reader, discovery };
++   return { logger, cache, database, config, reader, discovery, tokenManager };
+  };
+}
+```
+
+Finally, pull the `tokenManager` from the search plugin environment and pass it to both collators.
+
+```diff
+// packages/backend/src/plugins/search.ts
+
+...
+export default async function createPlugin({
+  ...
++ tokenManager,
+}: PluginEnvironment) {
+  ...
+  indexBuilder.addCollator({
+    defaultRefreshIntervalSeconds: 600,
+    collator: DefaultCatalogCollator.fromConfig(config, {
+      discovery,
++     tokenManager,
+    }),
+  });
+
+  indexBuilder.addCollator({
+    defaultRefreshIntervalSeconds: 600,
+    collator: DefaultTechDocsCollator.fromConfig(config, {
+      discovery,
+      logger,
++     tokenManager,
+    }),
+  });
+
+  ...
+}
+```
diff --git a/docs/features/search/getting-started.md b/docs/features/search/getting-started.md
index 27219e529a..7c3717e22e 100644
--- a/docs/features/search/getting-started.md
+++ b/docs/features/search/getting-started.md
@@ -154,13 +154,17 @@ import { DefaultCatalogCollator } from '@backstage/plugin-catalog-backend';
 export default async function createPlugin({
   logger,
   discovery,
+  tokenManager,
 }: PluginEnvironment) {
   const searchEngine = new LunrSearchEngine({ logger });
   const indexBuilder = new IndexBuilder({ logger, searchEngine });
 
   indexBuilder.addCollator({
     defaultRefreshIntervalSeconds: 600,
-    collator: new DefaultCatalogCollator({ discovery }),
+    collator: new DefaultCatalogCollator({
+      discovery,
+      tokenManager,
+    }),
   });
 
   const { scheduler } = await indexBuilder.build();
@@ -285,7 +289,10 @@ const indexBuilder = new IndexBuilder({ logger, searchEngine });
 
 indexBuilder.addCollator({
   defaultRefreshIntervalSeconds: 600,
-  collator: new DefaultCatalogCollator({ discovery }),
+  collator: new DefaultCatalogCollator({
+    discovery,
+    tokenManager,
+  }),
 });
 
 indexBuilder.addCollator({
@@ -303,6 +310,9 @@ its `defaultRefreshIntervalSeconds` value, like this:
 ```typescript {3}
 indexBuilder.addCollator({
   defaultRefreshIntervalSeconds: 600,
-  collator: new DefaultCatalogCollator({ discovery }),
+  collator: new DefaultCatalogCollator({
+    discovery,
+    tokenManager,
+  }),
 });
 ```
diff --git a/docs/features/search/how-to-guides.md b/docs/features/search/how-to-guides.md
index 621d46b51e..4ba44b8ef4 100644
--- a/docs/features/search/how-to-guides.md
+++ b/docs/features/search/how-to-guides.md
@@ -2,7 +2,7 @@
 id: how-to-guides
 title: Search "HOW TO" guides
 sidebar_label: "HOW TO" guides
-description: Search "HOW TO" guides 
+description: Search "HOW TO" guides
 ---
 
 ## How to implement your own Search API
@@ -74,6 +74,7 @@ indexBuilder.addCollator({
   collator: DefaultTechDocsCollator.fromConfig(config, {
     discovery,
     logger,
+    tokenManager,
   }),
 });
 ```