Improved Tech-Insights documentation

Signed-off-by: Andre Wanlin <awanlin@rapidrtc.com>

.changeset/thick-comics-fold.md

@@ -0,0 +1,11 @@
+---
+'@backstage/plugin-tech-insights': patch
+'@backstage/plugin-tech-insights-backend': patch
+---
+
+Improved the Tech-Insights documentation:
+
+- `lifecycle` examples used `ttl` when it should be `timeToLive`
+- Added list of included FactRetrievers
+- Added full backend example using all included FactRetrievers
+- Added boolean scorecard example image showing results of backend example

plugins/tech-insights-backend/README.md

@@ -92,8 +92,8 @@ FactRetrieverRegistration also accepts an optional `lifecycle` configuration val
 
 ```ts
 const maxItems = { maxItems: 7 }; // Deletes all but 7 latest facts for each id/entity pair
-const ttl = { ttl: 1209600000 }; // (2 weeks) Deletes items older than 2 weeks
-const ttlWithAHumanReadableValue = { ttl: { weeks: 2 } }; // Deletes items older than 2 weeks
+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:
@@ -235,3 +235,130 @@ const myFactCheckerFactory = new JsonRulesEngineFactCheckerFactory({
 }),
 
 ```
+
+## 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 the 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<Router> {
+  const techInsightsContext = await buildTechInsightsContext({
+    logger: env.logger,
+    config: env.config,
+    database: env.database,
+    discovery: env.discovery,
+    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,
+  });
+}
+```

plugins/tech-insights/README.md

@@ -47,12 +47,8 @@ const serviceEntityPage = (
 
 It is not obligatory to pass title and description props to `EntityTechInsightsScorecardContent`. If those are left out, default values from `defaultCheckResultRenderers` in `CheckResultRenderer` will be taken, hence `Boolean scorecard` and `This card represents an overview of default boolean Backstage checks`.
 
-### Customize scorecards overview title and description:
+## Boolean Scorecard Example
 
-```tsx
-// packages/app/src/components/catalog/EntityPage.tsx
+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 boolean scorecard will look like this:
 
-## Links
-
-- [The Backstage homepage](https://backstage.io)
-```
+![Boolean Scorecard Example](./docs/boolean-scorecard-example.png)

plugins/tech-insights/package.json

@@ -12,6 +12,11 @@
   "backstage": {
     "role": "frontend-plugin"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "plugins/tech-insights"
+  },
   "scripts": {
     "build": "backstage-cli package build",
     "start": "backstage-cli package start",