From 4565cda05e2bb43ec1f0d2ca8e89f6e2dd34ca42 Mon Sep 17 00:00:00 2001 From: blam Date: Thu, 18 Apr 2024 20:50:44 +0200 Subject: [PATCH] Deprecate packages Signed-off-by: blam --- .changeset/migrate-1713466242003.md | 9 + .../README.md | 156 +------ .../package.json | 6 +- plugins/tech-insights-backend/README.md | 387 +----------------- plugins/tech-insights-backend/package.json | 6 +- plugins/tech-insights-common/README.md | 4 +- plugins/tech-insights-common/package.json | 6 +- plugins/tech-insights-node/README.md | 4 +- plugins/tech-insights-node/package.json | 6 +- plugins/tech-insights/README.md | 153 +------ plugins/tech-insights/package.json | 6 +- 11 files changed, 39 insertions(+), 704 deletions(-) create mode 100644 .changeset/migrate-1713466242003.md diff --git a/.changeset/migrate-1713466242003.md b/.changeset/migrate-1713466242003.md new file mode 100644 index 0000000000..f9dcca2ad2 --- /dev/null +++ b/.changeset/migrate-1713466242003.md @@ -0,0 +1,9 @@ +--- +'@backstage/plugin-tech-insights': patch +'@backstage/plugin-tech-insights-backend': patch +'@backstage/plugin-tech-insights-backend-module-jsonfc': patch +'@backstage/plugin-tech-insights-common': patch +'@backstage/plugin-tech-insights-node': patch +--- + +These packages have been migrated to the [backstage/community-plugins](https://github.com/backstage/community-plugins) repository. diff --git a/plugins/tech-insights-backend-module-jsonfc/README.md b/plugins/tech-insights-backend-module-jsonfc/README.md index 33b3ad7718..6f96adcaf7 100644 --- a/plugins/tech-insights-backend-module-jsonfc/README.md +++ b/plugins/tech-insights-backend-module-jsonfc/README.md @@ -1,155 +1,3 @@ -# Tech Insights Backend JSON Rules engine fact checker module +# Deprecated -This is an extension to module to tech-insights-backend plugin, which provides basic framework and functionality to implement tech insights within Backstage. - -This module provides functionality to run checks against a [json-rules-engine](https://github.com/CacheControl/json-rules-engine) and provide boolean logic by simply building checks using JSON conditions. - -## Getting started - -To add this FactChecker into your Tech Insights you need to install the module into your backend application: - -```bash -# From your Backstage root directory -yarn --cwd packages/backend add @backstage/plugin-tech-insights-backend-module-jsonfc -``` - -### Add to the backend - -```ts title="packages/backend/src/index.ts" -backend.add(import('@backstage/plugin-tech-insights-backend-module-jsonfc')); -``` - -This setup requires checks to be provided using the config. - -### Add to the backend (old) - -Modify the `techInsights.ts` file to contain a reference to the FactCheckers implementation. - -```diff -+import { JsonRulesEngineFactCheckerFactory } from '@backstage/plugin-tech-insights-backend-module-jsonfc'; - -+const myFactCheckerFactory = new JsonRulesEngineFactCheckerFactory({ -+ checks: [], -+ logger: env.logger, -+}), - - const builder = buildTechInsightsContext({ - logger: env.logger, - config: env.config, - database: env.database, - discovery: env.discovery, - tokenManager: env.tokenManager, - factRetrievers: [myFactRetrieverRegistration], -+ factCheckerFactory: myFactCheckerFactory - }); -``` - -By default, this implementation comes with an in-memory storage to store checks. You can inject an additional data store by adding an implementation of `TechInsightCheckRegistry` into the constructor options when creating a `JsonRulesEngineFactCheckerFactory`. That can be done as follows - -```diff - const myTechInsightCheckRegistry: TechInsightCheckRegistry = // snip - const myFactCheckerFactory = new JsonRulesEngineFactCheckerFactory({ - checks: [], - logger: env.logger, -+ checkRegistry: myTechInsightCheckRegistry - }), - -``` - -## Adding checks in code - -Checks for this FactChecker are constructed as [`json-rules-engine` compatible JSON rules](https://github.com/CacheControl/json-rules-engine/blob/master/docs/rules.md#conditions). A check could look like the following for example: - -```ts -import { - JSON_RULE_ENGINE_CHECK_TYPE, - TechInsightJsonRuleCheck, -} from '@backstage/plugin-tech-insights-backend-module-jsonfc'; - -export const exampleCheck: TechInsightJsonRuleCheck = { - id: 'demodatacheck', // Unique identifier of this check - name: 'demodatacheck', // A human readable name of this check to be displayed in the UI - type: JSON_RULE_ENGINE_CHECK_TYPE, // Type identifier of the check. Used to run logic against, determine persistence option to use and render correct components on the UI - description: 'A fact check for demoing purposes', // A description to be displayed in the UI - factIds: ['documentation-number-factretriever'], // References to fact ids that this check uses. See documentation on FactRetrievers for more information on these - rule: { - // The actual rule - conditions: { - all: [ - // 2 options are available, all and any conditions. - { - fact: 'examplenumberfact', // Reference to an individual fact to check against - operator: 'greaterThanInclusive', // Operator to use. See: https://github.com/CacheControl/json-rules-engine/blob/master/docs/rules.md#operators for more - value: 2, // The threshold value that the fact must satisfy - }, - ], - }, - }, - successMetadata: { - // Additional metadata to be returned if the check has passed - link: 'https://link.to.some.information.com', - }, - failureMetadata: { - // Additional metadata to be returned if the check has failed - link: 'https://sonar.mysonarqube.com/increasing-number-value', - }, -}; -``` - -## Adding checks in config - -Example: - -```yaml title="app-config.yaml" -techInsights: - factChecker: - checks: - groupOwnerCheck: - type: json-rules-engine - name: Group Owner Check - description: Verifies that a group has been set as the spec.owner for this entity - factIds: - - entityOwnershipFactRetriever - rule: - conditions: - all: - - fact: hasGroupOwner - operator: equal - value: true -``` - -### More than one `factIds` for a check. - -When more than one is supplied, the requested fact **MUST** be present in at least one of the fact retrievers. -The order of the fact retrievers defined in the `factIds` array has no bearing on the checks, the check will merge all facts from the various retrievers, and then check against latest fact . - -# Custom operators - -json-rules-engine supports a limited [number of built-in operators](https://github.com/CacheControl/json-rules-engine/blob/master/docs/rules.md#operators) that can be used in conditions. You can add your own operators by adding them to the `operators` array in the `JsonRulesEngineFactCheckerFactory` constructor. For example: - -```diff -+ import { Operator } from 'json-rules-engine'; - -const myFactCheckerFactory = new JsonRulesEngineFactCheckerFactory({ - checks: [], - logger: env.logger, -+ operators: [ new Operator("startsWith", (a, b) => a.startsWith(b) ] -}) -``` - -And you can then use it in your checks like this: - -```js -... -rule: { - conditions: { - any: [ - { - fact: 'version', - operator: 'startsWith', - value: '12', - }, - ], - }, -} -``` +This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-tech-insights-backend-module-jsonfc` instead. diff --git a/plugins/tech-insights-backend-module-jsonfc/package.json b/plugins/tech-insights-backend-module-jsonfc/package.json index 1bde53d76d..db9438aa21 100644 --- a/plugins/tech-insights-backend-module-jsonfc/package.json +++ b/plugins/tech-insights-backend-module-jsonfc/package.json @@ -2,7 +2,8 @@ "name": "@backstage/plugin-tech-insights-backend-module-jsonfc", "version": "0.1.49", "backstage": { - "role": "backend-plugin-module" + "role": "backend-plugin-module", + "moved": "@backstage-community/plugin-tech-insights-backend-module-jsonfc" }, "publishConfig": { "access": "public", @@ -53,5 +54,6 @@ "@backstage/backend-test-utils": "workspace:^", "@backstage/cli": "workspace:^" }, - "configSchema": "config.json" + "configSchema": "config.json", + "deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-tech-insights-backend-module-jsonfc instead." } diff --git a/plugins/tech-insights-backend/README.md b/plugins/tech-insights-backend/README.md index 56b927a10e..3b19c5a310 100644 --- a/plugins/tech-insights-backend/README.md +++ b/plugins/tech-insights-backend/README.md @@ -1,386 +1,3 @@ -# Tech Insights Backend +# Deprecated -This is the backend for the default Backstage Tech Insights feature. -This provides the API for the frontend tech insights, scorecards and fact visualization functionality, -as well as a framework to run fact retrievers and store fact values in to a data store. - -## Installation - -### Install the package - -```bash -# From your Backstage root directory -yarn --cwd packages/backend add @backstage/plugin-tech-insights-backend -``` - -### Adding the plugin to your `packages/backend` - -```ts title="packages/backend/src/index.ts" -backend.add(import('@backstage/plugin-tech-insights-backend')); -``` - -You can use the extension points [@backstage/plugin-tech-insights-node](../tech-insights-node) -to add your `FactRetriever` or set a `FactCheckerFactory`. - -The built-in `FactRetrievers`: - -- `entityMetadataFactRetriever` -- `entityOwnershipFactRetriever` -- `techdocsFactRetriever` - -`FactRetrievers` only get registered if they get configured: - -```yaml title="app-config.yaml" -techInsights: - factRetrievers: - entityOwnershipFactRetriever: - cadence: '*/15 * * * *' - lifecycle: { timeToLive: { weeks: 2 } } -``` - -### Adding the plugin to your `packages/backend` (old) - -You'll need to add the plugin to the router in your `backend` package. You can -do this by creating a file called `packages/backend/src/plugins/techInsights.ts`. An example content for `techInsights.ts` could be something like this. - -```ts -import { - createRouter, - buildTechInsightsContext, -} from '@backstage/plugin-tech-insights-backend'; -import { Router } from 'express'; -import { PluginEnvironment } from '../types'; - -export default async function createPlugin( - env: PluginEnvironment, -): Promise { - const builder = buildTechInsightsContext({ - logger: env.logger, - config: env.config, - database: env.database, - discovery: env.discovery, - scheduler: env.scheduler, - tokenManager: env.tokenManager, - factRetrievers: [], // Fact retrievers registrations you want tech insights to use - }); - - return await createRouter({ - ...(await builder), - logger: env.logger, - config: env.config, - }); -} -``` - -With the `techInsights.ts` router setup in place, add the router to -`packages/backend/src/index.ts`: - -```diff -+import techInsights from './plugins/techInsights'; - - async function main() { - ... - const createEnv = makeCreateEnv(config); - - const catalogEnv = useHotMemoize(module, () => createEnv('catalog')); -+ const techInsightsEnv = useHotMemoize(module, () => createEnv('tech_insights')); - - const apiRouter = Router(); -+ apiRouter.use('/tech-insights', await techInsights(techInsightsEnv)); - ... - apiRouter.use(notFoundHandler()); - } -``` - -### Adding fact retrievers - -At this point the Tech Insights backend is installed in your backend package, but -you will not have any fact retrievers present in your application. To have the implemented FactRetrieverEngine within this package to be able to retrieve and store fact data into the database, you need to add these. - -To create factRetrieverRegistration you need to implement `FactRetriever` interface defined in `@backstage/plugin-tech-insights-node` package (see [Creating fact retrievers](#creating-fact-retrievers) for details). After you have implemented this interface you can wrap that into a registration object like follows: - -```ts -import { createFactRetrieverRegistration } from '@backstage/plugin-tech-insights-backend'; - -const myFactRetriever = { - /** - * snip - */ -}; - -const myFactRetrieverRegistration = createFactRetrieverRegistration({ - cadence: '1 * 2 * * ', // On the first minute of the second day of the month - factRetriever: myFactRetriever, -}); -``` - -FactRetrieverRegistration also accepts an optional `lifecycle` configuration value. This can be either MaxItems or TTL (time to live). Valid options for this value are either a number for MaxItems or a Luxon duration like object for TTL. For example: - -```ts -const maxItems = { maxItems: 7 }; // Deletes all but 7 latest facts for each id/entity pair -const ttl = { timeToLive: 1209600000 }; // (2 weeks) Deletes items older than 2 weeks -const ttlWithAHumanReadableValue = { timeToLive: { weeks: 2 } }; // Deletes items older than 2 weeks -``` - -To register these fact retrievers to your application you can modify the example `techInsights.ts` file shown above like this: - -```diff -const builder = buildTechInsightsContext({ - logger: env.logger, - config: env.config, - database: env.database, - discovery: env.discovery, - tokenManager: env.tokenManager, - scheduler: env.scheduler, -- factRetrievers: [], -+ factRetrievers: [myFactRetrieverRegistration], -}); -``` - -#### Running fact retrievers in a multi-instance installation - -The Tech Insights plugin utilizes the `PluginTaskScheduler` for scheduling tasks and coordinating the task invocation across instances. See [the PluginTaskScheduler documentation](https://backstage.io/docs/reference/backend-tasks.plugintaskscheduler) for more information. - -### Creating Fact Retrievers - -A Fact Retriever consist of four required and one optional parts: - -1. `id` - unique identifier of a fact retriever -2. `version`: A semver string indicating the current version of the schema and the handler -3. `schema` - A versioned schema defining the shape of data a fact retriever returns -4. `handler` - An asynchronous function handling the logic of retrieving and returning facts for an entity -5. `entityFilter` - (Optional) EntityFilter object defining the entity kinds, types and/or names this fact retriever handles - -An example implementation of a FactRetriever could for example be as follows: - -```ts -import { FactRetriever } from '@backstage/plugin-tech-insights-node'; - -const myFactRetriever: FactRetriever = { - id: 'documentation-number-factretriever', // unique identifier of the fact retriever - version: '0.1.1', // SemVer version number of this fact retriever schema. This should be incremented if the implementation changes - entityFilter: [{ kind: 'component' }], // EntityFilter to be used in the future (creating checks, graphs etc.) to figure out which entities this fact retrieves data for. - schema: { - // Name/identifier of an individual fact that this retriever returns - examplenumberfact: { - type: 'integer', // Type of the fact - description: 'A fact of a number', // Description of the fact - }, - }, - handler: async ctx => { - // Handler function that retrieves the fact - const { discovery, config, logger } = ctx; - const catalogClient = new CatalogClient({ - discoveryApi: discovery, - }); - const entities = await catalogClient.getEntities( - { - filter: [{ kind: 'component' }], - }, - { token }, - ); - /** - * snip: Do complex logic to retrieve facts from external system or calculate fact values - */ - - // Respond with an array of entity/fact values - return entities.items.map(it => { - return { - // Entity information that this fact relates to - entity: { - namespace: it.metadata.namespace, - kind: it.kind, - name: it.metadata.name, - }, - - // All facts that this retriever returns - facts: { - examplenumberfact: 2, // - }, - // (optional) timestamp to use as a Luxon DateTime object - }; - }); - }, -}; -``` - -### Adding a fact checker - -This module comes with a possibility to additionally add a fact checker and expose fact checking endpoints from the API. To be able to enable this feature you need to add a FactCheckerFactory implementation to be part of the `DefaultTechInsightsBuilder` constructor call. - -There is a default FactChecker implementation provided in module `@backstage/plugin-tech-insights-backend-module-jsonfc`. This implementation uses `json-rules-engine` as the underlying functionality to run checks. If you want to implement your own FactChecker, for example to be able to handle other than `boolean` result types, you can do so by implementing `FactCheckerFactory` and `FactChecker` interfaces from `@backstage/plugin-tech-insights-common` package. - -To add the default FactChecker into your Tech Insights you need to install the module into your backend application: - -```bash -# From your Backstage root directory -yarn --cwd packages/backend add @backstage/plugin-tech-insights-backend-module-jsonfc -``` - -and modify the `techInsights.ts` file to contain a reference to the FactChecker implementation. - -```diff -+import { JsonRulesEngineFactCheckerFactory } from '@backstage/plugin-tech-insights-backend-module-jsonfc'; - -+const myFactCheckerFactory = new JsonRulesEngineFactCheckerFactory({ -+ checks: [], -+ logger: env.logger, -+}), - - const builder = new DefaultTechInsightsBuilder({ - logger: env.logger, - config: env.config, - database: env.database, - discovery: env.discovery, - tokenManager: env.tokenManager, - factRetrievers: [myFactRetrieverRegistration], -+ factCheckerFactory: myFactCheckerFactory - }); -``` - -NOTE: You need a Fact Checker Factory to get access to the backend routes that will allow the facts to be checked. If you don't have a Fact Checker Factory you will see 404s and potentially other errors. - -To be able to run checks, you need to additionally add individual checks into your FactChecker implementation. For examples how to add these, you can check the documentation of the individual implementation of the FactChecker - -#### Modifying check persistence - -The default FactChecker implementation comes with an in-memory storage to store checks. You can inject an additional data store by adding an implementation of `TechInsightCheckRegistry` into the constructor options when creating a `JsonRulesEngineFactCheckerFactory`. That can be done as follows: - -```diff -const myTechInsightCheckRegistry: TechInsightCheckRegistry = // snip -const myFactCheckerFactory = new JsonRulesEngineFactCheckerFactory({ - checks: [], - logger: env.logger, -+ checkRegistry: myTechInsightCheckRegistry -}), - -``` - -## Included FactRetrievers - -There are three FactRetrievers that come out of the box with Tech Insights: - -- `entityMetadataFactRetriever`: Generates facts which indicate the completeness of entity metadata -- `entityOwnershipFactRetriever`: Generates facts which indicate the quality of data in the spec.owner field -- `techdocsFactRetriever`: Generates facts related to the completeness of techdocs configuration for entities - -## Backend Example - -Here's an example backend setup that will use the three included fact retrievers so you can get an idea of how this all works. This will be the entire contents of your `techInsights.ts` file found at `\packages\backend\src\plugins` as per [Adding the plugin to your `packages/backend`](#adding-the-plugin-to-your-packagesbackend) - -```ts -import { - createRouter, - buildTechInsightsContext, - createFactRetrieverRegistration, - entityOwnershipFactRetriever, - entityMetadataFactRetriever, - techdocsFactRetriever, -} from '@backstage/plugin-tech-insights-backend'; -import { Router } from 'express'; -import { PluginEnvironment } from '../types'; -import { - JsonRulesEngineFactCheckerFactory, - JSON_RULE_ENGINE_CHECK_TYPE, -} from '@backstage/plugin-tech-insights-backend-module-jsonfc'; - -const ttlTwoWeeks = { timeToLive: { weeks: 2 } }; - -export default async function createPlugin( - env: PluginEnvironment, -): Promise { - const techInsightsContext = await buildTechInsightsContext({ - logger: env.logger, - config: env.config, - database: env.database, - discovery: env.discovery, - tokenManager: env.tokenManager, - scheduler: env.scheduler, - factRetrievers: [ - createFactRetrieverRegistration({ - cadence: '0 */6 * * *', // Run every 6 hours - https://crontab.guru/#0_*/6_*_*_* - factRetriever: entityOwnershipFactRetriever, - lifecycle: ttlTwoWeeks, - }), - createFactRetrieverRegistration({ - cadence: '0 */6 * * *', - factRetriever: entityMetadataFactRetriever, - lifecycle: ttlTwoWeeks, - }), - createFactRetrieverRegistration({ - cadence: '0 */6 * * *', - factRetriever: techdocsFactRetriever, - lifecycle: ttlTwoWeeks, - }), - ], - factCheckerFactory: new JsonRulesEngineFactCheckerFactory({ - logger: env.logger, - checks: [ - { - id: 'groupOwnerCheck', - type: JSON_RULE_ENGINE_CHECK_TYPE, - name: 'Group Owner Check', - description: - 'Verifies that a Group has been set as the owner for this entity', - factIds: ['entityOwnershipFactRetriever'], - rule: { - conditions: { - all: [ - { - fact: 'hasGroupOwner', - operator: 'equal', - value: true, - }, - ], - }, - }, - }, - { - id: 'titleCheck', - type: JSON_RULE_ENGINE_CHECK_TYPE, - name: 'Title Check', - description: - 'Verifies that a Title, used to improve readability, has been set for this entity', - factIds: ['entityMetadataFactRetriever'], - rule: { - conditions: { - all: [ - { - fact: 'hasTitle', - operator: 'equal', - value: true, - }, - ], - }, - }, - }, - { - id: 'techDocsCheck', - type: JSON_RULE_ENGINE_CHECK_TYPE, - name: 'TechDocs Check', - description: - 'Verifies that TechDocs has been enabled for this entity', - factIds: ['techdocsFactRetriever'], - rule: { - conditions: { - all: [ - { - fact: 'hasAnnotationBackstageIoTechdocsRef', - operator: 'equal', - value: true, - }, - ], - }, - }, - }, - ], - }), - }); - - return await createRouter({ - ...techInsightsContext, - logger: env.logger, - config: env.config, - }); -} -``` +This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-tech-insights-backend` instead. diff --git a/plugins/tech-insights-backend/package.json b/plugins/tech-insights-backend/package.json index c536ae287a..64a6d651e8 100644 --- a/plugins/tech-insights-backend/package.json +++ b/plugins/tech-insights-backend/package.json @@ -2,7 +2,8 @@ "name": "@backstage/plugin-tech-insights-backend", "version": "0.5.31", "backstage": { - "role": "backend-plugin" + "role": "backend-plugin", + "moved": "@backstage-community/plugin-tech-insights-backend" }, "publishConfig": { "access": "public", @@ -67,5 +68,6 @@ "supertest": "^6.1.3", "wait-for-expect": "^3.0.2" }, - "configSchema": "config.d.ts" + "configSchema": "config.d.ts", + "deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-tech-insights-backend instead." } diff --git a/plugins/tech-insights-common/README.md b/plugins/tech-insights-common/README.md index af14ef0e0d..9cfc812797 100644 --- a/plugins/tech-insights-common/README.md +++ b/plugins/tech-insights-common/README.md @@ -1,3 +1,3 @@ -# Tech Insights Common +# Deprecated -Common types and functionalities for tech insights shared in an isomorphic manner between BE and FE implementations. +This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-tech-insights-common` instead. diff --git a/plugins/tech-insights-common/package.json b/plugins/tech-insights-common/package.json index bcaaca84e5..394003c575 100644 --- a/plugins/tech-insights-common/package.json +++ b/plugins/tech-insights-common/package.json @@ -2,7 +2,8 @@ "name": "@backstage/plugin-tech-insights-common", "version": "0.2.12", "backstage": { - "role": "common-library" + "role": "common-library", + "moved": "@backstage-community/plugin-tech-insights-common" }, "publishConfig": { "access": "public", @@ -42,5 +43,6 @@ }, "devDependencies": { "@backstage/cli": "workspace:^" - } + }, + "deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-tech-insights-common instead." } diff --git a/plugins/tech-insights-node/README.md b/plugins/tech-insights-node/README.md index 4065611837..1de6003843 100644 --- a/plugins/tech-insights-node/README.md +++ b/plugins/tech-insights-node/README.md @@ -1,3 +1,3 @@ -# Tech Insights Node +# Deprecated -Common types and functionalities for tech insights backend implementations to be shared between tech-insights-backend and individual implementations of FactRetrievers, FactCheckers and their persistence options. +This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-tech-insights-node` instead. diff --git a/plugins/tech-insights-node/package.json b/plugins/tech-insights-node/package.json index 4d18010237..aab0a666b8 100644 --- a/plugins/tech-insights-node/package.json +++ b/plugins/tech-insights-node/package.json @@ -2,7 +2,8 @@ "name": "@backstage/plugin-tech-insights-node", "version": "0.6.0", "backstage": { - "role": "node-library" + "role": "node-library", + "moved": "@backstage-community/plugin-tech-insights-node" }, "publishConfig": { "access": "public", @@ -45,5 +46,6 @@ }, "devDependencies": { "@backstage/cli": "workspace:^" - } + }, + "deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-tech-insights-node instead." } diff --git a/plugins/tech-insights/README.md b/plugins/tech-insights/README.md index 9145e892e7..46c9f2d9a2 100644 --- a/plugins/tech-insights/README.md +++ b/plugins/tech-insights/README.md @@ -1,152 +1,3 @@ -# Tech Insights +# Deprecated -This plugin provides the UI for the `@backstage/tech-insights-backend` plugin, in order to display results of the checks running following the rules and the logic defined in the `@backstage/tech-insights-backend` plugin itself. - -Main areas covered by this plugin currently are: - -- Providing an overview for default boolean checks in a form of Scorecards. - -- Providing an option to render different custom components based on type of the checks running in the backend. - -## Installation - -### Install the plugin - -```bash -# From your Backstage root directory -yarn --cwd packages/app add @backstage/plugin-tech-insights -``` - -### Add boolean checks overview (Scorecards) page to the EntityPage: - -```tsx -// packages/app/src/components/catalog/EntityPage.tsx - -import { EntityTechInsightsScorecardContent } from '@backstage/plugin-tech-insights'; - -const serviceEntityPage = ( - - - {overviewContent} - - - {cicdContent} - - ... - - - - ... - -); -``` - -It is obligatory to pass `title` prop to `EntityTechInsightsScorecardContent`, `description` prop is optional. - -If you like to display multiple cards in a `EntityLayout.Route` use `EntityTechInsightsScorecardCard`. - -You can pass an array `checksId` as a prop with the [Fact Retrievers ids](../tech-insights-backend#creating-fact-retrievers) to limit which checks you want to show in this card. If you don't pass, the default value is show all checks. - -```tsx - -``` - -If you want to show checks in the overview of an entity use `EntityTechInsightsScorecardCard`. - -```tsx -// packages/app/src/components/catalog/EntityPage.tsx - -import { EntityTechInsightsScorecardCard } from '@backstage/plugin-tech-insights'; - -const overviewContent = ( - - {entityWarningContent} - - - - - - - ... - - - - -); -``` - -## Boolean Scorecard Example - -If you follow the [Backend Example](https://github.com/backstage/backstage/tree/master/plugins/tech-insights-backend#backend-example), once the needed facts have been generated the default boolean scorecard will look like this: - -![Boolean Scorecard Example](./docs/boolean-scorecard-example.png) - -## Adding custom rendering components - -Default scorecard implementation displays only `json-rules-engine` check results. If you would like to support different types, you need to inject custom rendering components to the `TechInsightsClient` constructor. - -```ts -// packages/app/src/apis.ts - -export const apis: AnyApiFactory[] = [ -... - createApiFactory({ - api: techInsightsApiRef, - deps: { discoveryApi: discoveryApiRef, identityApi: identityApiRef }, - factory: ({ discoveryApi, identityApi }) => - new TechInsightsClient({ - discoveryApi, - identityApi, - renderers: [ - jsonRulesEngineCheckResultRenderer, // default json-rules-engine renderer - myCustomBooleanRenderer, // custom renderer - ], - }), - }), -... -]; -``` - -```tsx -// packages/app/src/components/myCustomBooleanRenderer.tsx - -export const myCustomBooleanRenderer: CheckResultRenderer = { - type: 'boolean', - component: (checkResult: CheckResult) => ( - - ), -}; -``` - -It's also possible to customize the description. Both strings and React components are accepted. As an example, you would like -to display another information if the check has failed. In such cases, you could do something like the following: - -```tsx -// packages/app/src/components/myCustomBooleanRenderer.tsx - -export const myCustomBooleanRenderer: CheckResultRenderer = { - type: 'boolean', - component: (checkResult: CheckResult) => ( - - ), - description: (checkResult: CheckResult) => ( - <> - { - checkResult.result - ? checkResult.check.description // In case of success, return the same description - : `The check has failed! ${checkResult.check.description}` // Add a prefix text if the check failed - } - - ), -}; -``` +This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-tech-insights` instead. diff --git a/plugins/tech-insights/package.json b/plugins/tech-insights/package.json index 61ed06e44e..1716f1fd35 100644 --- a/plugins/tech-insights/package.json +++ b/plugins/tech-insights/package.json @@ -2,7 +2,8 @@ "name": "@backstage/plugin-tech-insights", "version": "0.3.26", "backstage": { - "role": "frontend-plugin" + "role": "frontend-plugin", + "moved": "@backstage-community/plugin-tech-insights" }, "publishConfig": { "access": "public", @@ -57,5 +58,6 @@ "react": "^16.13.1 || ^17.0.0 || ^18.0.0", "react-dom": "^16.13.1 || ^17.0.0 || ^18.0.0", "react-router-dom": "6.0.0-beta.0 || ^6.3.0" - } + }, + "deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-tech-insights instead." }