From 3c39045e2bcee481ae410e6115b8abbc449147dc Mon Sep 17 00:00:00 2001 From: Camila Belo Date: Sat, 14 Oct 2023 12:08:57 +0200 Subject: [PATCH] refactor: rename stack overflow backend module Signed-off-by: Camila Belo --- .changeset/chilly-terms-behave.md | 2 +- .changeset/giant-cycles-end.md | 2 +- .../integrating-search-into-plugins.md | 2 +- .../.eslintrc.js | 0 .../README.md | 97 +++++++++++++++++++ .../alpha-api-report.md | 2 +- .../api-report.md | 2 +- .../catalog-info.yaml | 4 +- .../config.d.ts | 0 .../package.json | 2 +- .../src/alpha.test.ts | 0 .../src/alpha.ts | 0 ...ckOverflowQuestionsCollatorFactory.test.ts | 0 .../StackOverflowQuestionsCollatorFactory.ts | 0 .../src/collators/index.ts | 0 .../src/index.ts | 0 .../README.md | 30 ------ plugins/stack-overflow-backend/api-report.md | 6 +- plugins/stack-overflow-backend/package.json | 2 +- plugins/stack-overflow-backend/src/index.ts | 10 +- yarn.lock | 6 +- 21 files changed, 117 insertions(+), 50 deletions(-) rename plugins/{search-backend-module-stack-overflow => search-backend-module-stack-overflow-collator}/.eslintrc.js (100%) create mode 100644 plugins/search-backend-module-stack-overflow-collator/README.md rename plugins/{search-backend-module-stack-overflow => search-backend-module-stack-overflow-collator}/alpha-api-report.md (92%) rename plugins/{search-backend-module-stack-overflow => search-backend-module-stack-overflow-collator}/api-report.md (98%) rename plugins/{search-backend-module-stack-overflow => search-backend-module-stack-overflow-collator}/catalog-info.yaml (79%) rename plugins/{search-backend-module-stack-overflow => search-backend-module-stack-overflow-collator}/config.d.ts (100%) rename plugins/{search-backend-module-stack-overflow => search-backend-module-stack-overflow-collator}/package.json (99%) rename plugins/{search-backend-module-stack-overflow => search-backend-module-stack-overflow-collator}/src/alpha.test.ts (100%) rename plugins/{search-backend-module-stack-overflow => search-backend-module-stack-overflow-collator}/src/alpha.ts (100%) rename plugins/{search-backend-module-stack-overflow => search-backend-module-stack-overflow-collator}/src/collators/StackOverflowQuestionsCollatorFactory.test.ts (100%) rename plugins/{search-backend-module-stack-overflow => search-backend-module-stack-overflow-collator}/src/collators/StackOverflowQuestionsCollatorFactory.ts (100%) rename plugins/{search-backend-module-stack-overflow => search-backend-module-stack-overflow-collator}/src/collators/index.ts (100%) rename plugins/{search-backend-module-stack-overflow => search-backend-module-stack-overflow-collator}/src/index.ts (100%) delete mode 100644 plugins/search-backend-module-stack-overflow/README.md diff --git a/.changeset/chilly-terms-behave.md b/.changeset/chilly-terms-behave.md index 47250364bf..b514bc45c8 100644 --- a/.changeset/chilly-terms-behave.md +++ b/.changeset/chilly-terms-behave.md @@ -1,5 +1,5 @@ --- -'@backstage/plugin-search-backend-module-stack-overflow': patch +'@backstage/plugin-search-backend-module-stack-overflow-collator': patch --- Extract a package for the Stack Overflow new backend system plugin. diff --git a/.changeset/giant-cycles-end.md b/.changeset/giant-cycles-end.md index 6f637e05dd..f69938ea25 100644 --- a/.changeset/giant-cycles-end.md +++ b/.changeset/giant-cycles-end.md @@ -2,6 +2,6 @@ '@backstage/plugin-stack-overflow-backend': patch --- -Deprecate package in favor of the new `@backstage/plugin-search-backend-module-stack-overflow` module. +Deprecate package in favor of the new `@backstage/plugin-search-backend-module-stack-overflow-collator` module. The search collator `requestParams` option is optional now, so its default value is `{ order: 'desc', sort: 'activity', site: 'stackoverflow' }` as defined in the `Try It` section on the [official Stack Overflow API documentation](https://api.stackexchange.com/docs/questions). diff --git a/docs/plugins/integrating-search-into-plugins.md b/docs/plugins/integrating-search-into-plugins.md index f2692d4e91..28c8b410e3 100644 --- a/docs/plugins/integrating-search-into-plugins.md +++ b/docs/plugins/integrating-search-into-plugins.md @@ -22,7 +22,7 @@ Imagine you have a plugin that is responsible for storing FAQ snippets in a data The search platform provides an interface (`DocumentCollatorFactory` from package `@backstage/plugin-search-common`) that allows you to do exactly that. It works by registering each of your entries as a "document" that later represents one search result each. -> You can always look at a working example, e.g. [StackOverflowQuestionsCollatorFactory](https://github.com/backstage/backstage/blob/master/plugins/search-backend-module-stack-overflow/src/collators/StackOverflowQuestionsCollatorFactory.ts), if you are unsure or want to follow best practices. +> You can always look at a working example, e.g. [StackOverflowQuestionsCollatorFactory](https://github.com/backstage/backstage/blob/master/plugins/search-backend-module-stack-overflow-collator/src/collators/StackOverflowQuestionsCollatorFactory.ts), if you are unsure or want to follow best practices. #### 1. Install collator interface dependencies diff --git a/plugins/search-backend-module-stack-overflow/.eslintrc.js b/plugins/search-backend-module-stack-overflow-collator/.eslintrc.js similarity index 100% rename from plugins/search-backend-module-stack-overflow/.eslintrc.js rename to plugins/search-backend-module-stack-overflow-collator/.eslintrc.js diff --git a/plugins/search-backend-module-stack-overflow-collator/README.md b/plugins/search-backend-module-stack-overflow-collator/README.md new file mode 100644 index 0000000000..914746cbf9 --- /dev/null +++ b/plugins/search-backend-module-stack-overflow-collator/README.md @@ -0,0 +1,97 @@ +# Stack Overflow Search Backend Module + +A plugin that provides stack overflow specific functionality that can be used in different ways (e.g. for search) to compose your Backstage App. + +## Getting started + +Before we begin, make sure: + +- You have created your own standalone Backstage app using @backstage/create-app and not using a fork of the backstage repository. If you haven't setup Backstage already, start [here](https://backstage.io/docs/getting-started/). + +To use any of the functionality this plugin provides, you need to start by configuring your App with the following config: + +```yaml +stackoverflow: + baseUrl: https://api.stackexchange.com/2.2 # alternative: your internal stack overflow instance +``` + +### Stack Overflow for Teams + +If you have a private Stack Overflow instance and/or a private Stack Overflow Team you will need to supply an API key or Personal Access Token. You can read more about how to set this up by going to [Stack Overflow's Help Page](https://stackoverflow.help/en/articles/4385859-stack-overflow-for-teams-api). + +The existing API key approach remains the default, to support the new v2.3 API and PAT authentication model you need to pass the team name and the new PAT into the existing apiAccessToken parameter to the new URL. See [15770](https://github.com/backstage/backstage/issues/15770) for more details. + +```yaml +stackoverflow: + baseUrl: https://api.stackexchange.com/2.2 # alternative: your internal stack overflow instance + apiKey: $STACK_OVERFLOW_API_KEY + apiAccessToken: $STACK_OVERFLOW_API_ACCESS_TOKEN +``` + +```yaml +stackoverflow: + baseUrl: https://api.stackoverflowteams.com/2.3 # alternative: your internal stack overflow instance + teamName: $STACK_OVERFLOW_TEAM_NAME + apiAccessToken: $STACK_OVERFLOW_API_ACCESS_TOKEN +``` + +## Areas of Responsibility + +This stack overflow backend plugin is primarily responsible for the following: + +- Provides a `StackOverflowQuestionsCollatorFactory`, which can be used in the search backend to index stack overflow questions to your Backstage Search. + +### Index Stack Overflow Questions to search + +Before you are able to start index stack overflow questions to search, you need to go through the [search getting started guide](https://backstage.io/docs/features/search/getting-started). + +When you have your `packages/backend/src/plugins/search.ts` file ready to make modifications, add the following code snippet to add the `StackOverflowQuestionsCollatorFactory`. Note that you can optionally modify the `requestParams`, otherwise it will defaults to `{ order: 'desc', sort: 'activity', site: 'stackoverflow' }` as done in the `Try It` section on the [official Stack Overflow API documentation](https://api.stackexchange.com/docs/questions). + +> Note: if your `baseUrl` is set to the external stack overflow api `https://api.stackexchange.com/2.2`, you can find optional and required parameters under the official API documentation under [`Usage of /questions GET`](https://api.stackexchange.com/docs/questions) + +```ts +indexBuilder.addCollator({ + schedule, + factory: StackOverflowQuestionsCollatorFactory.fromConfig(env.config, { + logger: env.logger, + requestParams: { + tagged: ['backstage'], + site: 'stackoverflow', + pagesize: 100, + }, + }), +}); +``` + +## New Backend System + +> DISCLAIMER: The new backend system is in alpha, and so are the search backend module support for the new backend system. We don't recommend you to migrate your backend installations to the new system yet. But if you want to experiment, you can find getting started guides below. + +This package exports a module that extends the search backend to also indexing the questions exposed by the [`Stack Overflow` API](https://api.stackexchange.com/docs/questions). + +### Installation + +Add the module package as a dependency: + +```bash +# From your Backstage root directory +yarn add --cwd packages/backend @backstage/plugin-search-backend-module-stack-overflow-collator +``` + +Add the collator to your backend instance, along with the search plugin itself: + +```tsx +// packages/backend/src/index.ts +import { createBackend } from '@backstage/backend-defaults'; + +const backend = createBackend(); +backend.add(import('@backstage/plugin-search-backend/alpha')); +backend.add( + import( + '@backstage/plugin-search-backend-module-stack-overflow-collator/alpha' + ), +); +backend.start(); +``` + +You may also want to add configuration parameters to your app-config, for example for controlling the scheduled indexing interval. These parameters should be placed under the `stackoverflow` key. See [the config definition file](https://github.com/backstage/backstage/blob/master/plugins/search-backend-module-stack-overflow/config.d.ts) for more details. diff --git a/plugins/search-backend-module-stack-overflow/alpha-api-report.md b/plugins/search-backend-module-stack-overflow-collator/alpha-api-report.md similarity index 92% rename from plugins/search-backend-module-stack-overflow/alpha-api-report.md rename to plugins/search-backend-module-stack-overflow-collator/alpha-api-report.md index 9d25cb0a7d..a77d5e9598 100644 --- a/plugins/search-backend-module-stack-overflow/alpha-api-report.md +++ b/plugins/search-backend-module-stack-overflow-collator/alpha-api-report.md @@ -1,4 +1,4 @@ -## API Report File for "@backstage/plugin-search-backend-module-stack-overflow" +## API Report File for "@backstage/plugin-search-backend-module-stack-overflow-collator" > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). diff --git a/plugins/search-backend-module-stack-overflow/api-report.md b/plugins/search-backend-module-stack-overflow-collator/api-report.md similarity index 98% rename from plugins/search-backend-module-stack-overflow/api-report.md rename to plugins/search-backend-module-stack-overflow-collator/api-report.md index 795b30cac2..996260c4aa 100644 --- a/plugins/search-backend-module-stack-overflow/api-report.md +++ b/plugins/search-backend-module-stack-overflow-collator/api-report.md @@ -1,4 +1,4 @@ -## API Report File for "@backstage/plugin-search-backend-module-stack-overflow" +## API Report File for "@backstage/plugin-search-backend-module-stack-overflow-collator" > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). diff --git a/plugins/search-backend-module-stack-overflow/catalog-info.yaml b/plugins/search-backend-module-stack-overflow-collator/catalog-info.yaml similarity index 79% rename from plugins/search-backend-module-stack-overflow/catalog-info.yaml rename to plugins/search-backend-module-stack-overflow-collator/catalog-info.yaml index 9075d1d591..ed73bd0eca 100644 --- a/plugins/search-backend-module-stack-overflow/catalog-info.yaml +++ b/plugins/search-backend-module-stack-overflow-collator/catalog-info.yaml @@ -1,8 +1,8 @@ apiVersion: backstage.io/v1alpha1 kind: Component metadata: - name: backstage-plugin-search-backend-module-stack-overflow - title: '@backstage/plugin-search-backend-module-stack-overflow' + name: backstage-plugin-search-backend-module-stack-overflow-collator + title: '@backstage/plugin-search-backend-module-stack-overflow-collator' description: A module for the search backend that exports stack overflow modules spec: lifecycle: experimental diff --git a/plugins/search-backend-module-stack-overflow/config.d.ts b/plugins/search-backend-module-stack-overflow-collator/config.d.ts similarity index 100% rename from plugins/search-backend-module-stack-overflow/config.d.ts rename to plugins/search-backend-module-stack-overflow-collator/config.d.ts diff --git a/plugins/search-backend-module-stack-overflow/package.json b/plugins/search-backend-module-stack-overflow-collator/package.json similarity index 99% rename from plugins/search-backend-module-stack-overflow/package.json rename to plugins/search-backend-module-stack-overflow-collator/package.json index 64ff4d32d3..6e0b484e40 100644 --- a/plugins/search-backend-module-stack-overflow/package.json +++ b/plugins/search-backend-module-stack-overflow-collator/package.json @@ -1,5 +1,5 @@ { - "name": "@backstage/plugin-search-backend-module-stack-overflow", + "name": "@backstage/plugin-search-backend-module-stack-overflow-collator", "description": "A module for the search backend that exports stack overflow modules", "version": "0.0.0", "main": "src/index.ts", diff --git a/plugins/search-backend-module-stack-overflow/src/alpha.test.ts b/plugins/search-backend-module-stack-overflow-collator/src/alpha.test.ts similarity index 100% rename from plugins/search-backend-module-stack-overflow/src/alpha.test.ts rename to plugins/search-backend-module-stack-overflow-collator/src/alpha.test.ts diff --git a/plugins/search-backend-module-stack-overflow/src/alpha.ts b/plugins/search-backend-module-stack-overflow-collator/src/alpha.ts similarity index 100% rename from plugins/search-backend-module-stack-overflow/src/alpha.ts rename to plugins/search-backend-module-stack-overflow-collator/src/alpha.ts diff --git a/plugins/search-backend-module-stack-overflow/src/collators/StackOverflowQuestionsCollatorFactory.test.ts b/plugins/search-backend-module-stack-overflow-collator/src/collators/StackOverflowQuestionsCollatorFactory.test.ts similarity index 100% rename from plugins/search-backend-module-stack-overflow/src/collators/StackOverflowQuestionsCollatorFactory.test.ts rename to plugins/search-backend-module-stack-overflow-collator/src/collators/StackOverflowQuestionsCollatorFactory.test.ts diff --git a/plugins/search-backend-module-stack-overflow/src/collators/StackOverflowQuestionsCollatorFactory.ts b/plugins/search-backend-module-stack-overflow-collator/src/collators/StackOverflowQuestionsCollatorFactory.ts similarity index 100% rename from plugins/search-backend-module-stack-overflow/src/collators/StackOverflowQuestionsCollatorFactory.ts rename to plugins/search-backend-module-stack-overflow-collator/src/collators/StackOverflowQuestionsCollatorFactory.ts diff --git a/plugins/search-backend-module-stack-overflow/src/collators/index.ts b/plugins/search-backend-module-stack-overflow-collator/src/collators/index.ts similarity index 100% rename from plugins/search-backend-module-stack-overflow/src/collators/index.ts rename to plugins/search-backend-module-stack-overflow-collator/src/collators/index.ts diff --git a/plugins/search-backend-module-stack-overflow/src/index.ts b/plugins/search-backend-module-stack-overflow-collator/src/index.ts similarity index 100% rename from plugins/search-backend-module-stack-overflow/src/index.ts rename to plugins/search-backend-module-stack-overflow-collator/src/index.ts diff --git a/plugins/search-backend-module-stack-overflow/README.md b/plugins/search-backend-module-stack-overflow/README.md deleted file mode 100644 index cba9617ea8..0000000000 --- a/plugins/search-backend-module-stack-overflow/README.md +++ /dev/null @@ -1,30 +0,0 @@ -# search-backend-module-stack-overflow - -> DISCLAIMER: The new backend system is in alpha, and so are the search backend module support for the new backend system. We don't recommend you to migrate your backend installations to the new system yet. But if you want to experiment, you can find getting started guides below. - -This package exports a module that extends the search backend to also indexing the questions exposed by the [`Stack Overflow` API](https://api.stackexchange.com/docs/questions). - -## Installation - -Add the module package as a dependency: - -```bash -# From your Backstage root directory -yarn add --cwd packages/backend @backstage/plugin-search-backend-module-stack-overflow -``` - -Add the collator to your backend instance, along with the search plugin itself: - -```tsx -// packages/backend/src/index.ts -import { createBackend } from '@backstage/backend-defaults'; - -const backend = createBackend(); -backend.add(import('@backstage/plugin-search-backend/alpha')); -backend.add( - import('@backstage/plugin-search-backend-module-stack-overflow/alpha'), -); -backend.start(); -``` - -You may also want to add configuration parameters to your app-config, for example for controlling the scheduled indexing interval. These parameters should be placed under the `stackoverflow` key. See [the config definition file](https://github.com/backstage/backstage/blob/master/plugins/search-backend-module-stack-overflow/config.d.ts) for more details. diff --git a/plugins/stack-overflow-backend/api-report.md b/plugins/stack-overflow-backend/api-report.md index d113f7a0b6..14dcdf2007 100644 --- a/plugins/stack-overflow-backend/api-report.md +++ b/plugins/stack-overflow-backend/api-report.md @@ -3,9 +3,9 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts -import { StackOverflowDocument as StackOverflowDocument_2 } from '@backstage/plugin-search-backend-module-stack-overflow'; -import { StackOverflowQuestionsCollatorFactory as StackOverflowQuestionsCollatorFactory_2 } from '@backstage/plugin-search-backend-module-stack-overflow'; -import { StackOverflowQuestionsRequestParams as StackOverflowQuestionsRequestParams_2 } from '@backstage/plugin-search-backend-module-stack-overflow'; +import { StackOverflowDocument as StackOverflowDocument_2 } from '@backstage/plugin-search-backend-module-stack-overflow-collator'; +import { StackOverflowQuestionsCollatorFactory as StackOverflowQuestionsCollatorFactory_2 } from '@backstage/plugin-search-backend-module-stack-overflow-collator'; +import { StackOverflowQuestionsRequestParams as StackOverflowQuestionsRequestParams_2 } from '@backstage/plugin-search-backend-module-stack-overflow-collator'; // @public @deprecated (undocumented) export type StackOverflowDocument = StackOverflowDocument_2; diff --git a/plugins/stack-overflow-backend/package.json b/plugins/stack-overflow-backend/package.json index 5235c33f1a..c7b65a5ef5 100644 --- a/plugins/stack-overflow-backend/package.json +++ b/plugins/stack-overflow-backend/package.json @@ -34,7 +34,7 @@ "dependencies": { "@backstage/backend-common": "workspace:^", "@backstage/config": "workspace:^", - "@backstage/plugin-search-backend-module-stack-overflow": "workspace:^", + "@backstage/plugin-search-backend-module-stack-overflow-collator": "workspace:^", "@backstage/plugin-search-common": "workspace:^", "node-fetch": "^2.6.7", "qs": "^6.9.4", diff --git a/plugins/stack-overflow-backend/src/index.ts b/plugins/stack-overflow-backend/src/index.ts index 269748424b..e676de15e2 100644 --- a/plugins/stack-overflow-backend/src/index.ts +++ b/plugins/stack-overflow-backend/src/index.ts @@ -25,19 +25,19 @@ import { StackOverflowQuestionsRequestParams as _StackOverflowQuestionsRequestParams, StackOverflowQuestionsCollatorFactory as _StackOverflowQuestionsCollatorFactory, StackOverflowQuestionsCollatorFactoryOptions as _StackOverflowQuestionsCollatorFactoryOptions, -} from '@backstage/plugin-search-backend-module-stack-overflow'; +} from '@backstage/plugin-search-backend-module-stack-overflow-collator'; /** * @public * @deprecated - * Import from `@backstage/plugin-search-backend-module-stack-overflow` instead. + * Import from `@backstage/plugin-search-backend-module-stack-overflow-collator` instead. */ export type StackOverflowDocument = _StackOverflowDocument; /** * @public * @deprecated - * Import from `@backstage/plugin-search-backend-module-stack-overflow` instead. + * Import from `@backstage/plugin-search-backend-module-stack-overflow-collator` instead. */ export type StackOverflowQuestionsRequestParams = _StackOverflowQuestionsRequestParams; @@ -45,7 +45,7 @@ export type StackOverflowQuestionsRequestParams = /** * @public * @deprecated - * Import from `@backstage/plugin-search-backend-module-stack-overflow` instead. + * Import from `@backstage/plugin-search-backend-module-stack-overflow-collator` instead. */ export type StackOverflowQuestionsCollatorFactoryOptions = _StackOverflowQuestionsCollatorFactory; @@ -53,7 +53,7 @@ export type StackOverflowQuestionsCollatorFactoryOptions = /** * @public * @deprecated - * Import from `@backstage/plugin-search-backend-module-stack-overflow` instead. + * Import from `@backstage/plugin-search-backend-module-stack-overflow-collator` instead. */ export const StackOverflowQuestionsCollatorFactory = _StackOverflowQuestionsCollatorFactory; diff --git a/yarn.lock b/yarn.lock index 6e2db68238..1267ee2cb4 100644 --- a/yarn.lock +++ b/yarn.lock @@ -8847,9 +8847,9 @@ __metadata: languageName: unknown linkType: soft -"@backstage/plugin-search-backend-module-stack-overflow@workspace:^, @backstage/plugin-search-backend-module-stack-overflow@workspace:plugins/search-backend-module-stack-overflow": +"@backstage/plugin-search-backend-module-stack-overflow-collator@workspace:^, @backstage/plugin-search-backend-module-stack-overflow-collator@workspace:plugins/search-backend-module-stack-overflow-collator": version: 0.0.0-use.local - resolution: "@backstage/plugin-search-backend-module-stack-overflow@workspace:plugins/search-backend-module-stack-overflow" + resolution: "@backstage/plugin-search-backend-module-stack-overflow-collator@workspace:plugins/search-backend-module-stack-overflow-collator" dependencies: "@backstage/backend-common": "workspace:^" "@backstage/backend-plugin-api": "workspace:^" @@ -9209,7 +9209,7 @@ __metadata: "@backstage/backend-test-utils": "workspace:^" "@backstage/cli": "workspace:^" "@backstage/config": "workspace:^" - "@backstage/plugin-search-backend-module-stack-overflow": "workspace:^" + "@backstage/plugin-search-backend-module-stack-overflow-collator": "workspace:^" "@backstage/plugin-search-backend-node": "workspace:^" "@backstage/plugin-search-common": "workspace:^" msw: ^1.0.0