Merge pull request #9488 from backstage/freben/move-template

move `TemplateEntityV1beta2` to `@backstage/plugin-scaffolder-common`

.changeset/beige-cherries-knock.md

@@ -0,0 +1,8 @@
+---
+'@backstage/plugin-scaffolder-common': patch
+---
+
+Added `TemplateEntityV1beta2` which was moved here from
+`@backstage/plugin-scaffolder-common`. It has also been marked as deprecated in
+the process - please consider [migrating to `v1beta3`
+templates](https://backstage.io/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3).

.changeset/modern-mayflies-join.md

@@ -0,0 +1,9 @@
+---
+'@backstage/plugin-catalog-backend': patch
+'@backstage/plugin-catalog-react': patch
+'@backstage/plugin-scaffolder': patch
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Use `TemplateEntityV1beta2` from `@backstage/plugin-scaffolder-common` instead
+of `@backstage/catalog-model`.

.changeset/rude-tables-grab.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder-common': minor
+---
+
+**BREAKING**: Removed the `templateEntityV1beta3Schema` export

.changeset/smart-rivers-reflect.md

@@ -0,0 +1,8 @@
+---
+'@backstage/catalog-model': minor
+---
+
+**BREAKING**: Removed `TemplateEntityV1beta2` from the model and moved it to
+`@backstage/plugin-scaffolder-common` where `TemplateEntityV1beta3` already
+lived. It has also been marked as deprecated in the process - please consider
+[migrating to `v1beta3` templates](https://backstage.io/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3).

packages/catalog-model/api-report.md

@@ -558,33 +558,6 @@ export { SystemEntityV1alpha1 };
 // @public
 export const systemEntityV1alpha1Validator: KindValidator;
 
-// @public
-export interface TemplateEntityV1beta2 extends Entity {
-  // (undocumented)
-  apiVersion: 'backstage.io/v1beta2';
-  // (undocumented)
-  kind: 'Template';
-  // (undocumented)
-  spec: {
-    type: string;
-    parameters?: JsonObject | JsonObject[];
-    steps: Array<{
-      id?: string;
-      name?: string;
-      action: string;
-      input?: JsonObject;
-      if?: string | boolean;
-    }>;
-    output?: {
-      [name: string]: string;
-    };
-    owner?: string;
-  };
-}
-
-// @public
-export const templateEntityV1beta2Validator: KindValidator;
-
 // @public
 interface UserEntityV1alpha1 extends Entity {
   // (undocumented)

packages/catalog-model/src/kinds/index.ts

@@ -50,8 +50,6 @@ export type {
   SystemEntityV1alpha1 as SystemEntity,
   SystemEntityV1alpha1,
 } from './SystemEntityV1alpha1';
-export { templateEntityV1beta2Validator } from './TemplateEntityV1beta2';
-export type { TemplateEntityV1beta2 } from './TemplateEntityV1beta2';
 export type { KindValidator } from './types';
 export { userEntityV1alpha1Validator } from './UserEntityV1alpha1';
 export type {

plugins/catalog-backend/package.json

@@ -39,6 +39,7 @@
     "@backstage/plugin-catalog-common": "^0.1.2",
     "@backstage/plugin-permission-common": "^0.4.0",
     "@backstage/plugin-permission-node": "^0.4.3",
+    "@backstage/plugin-scaffolder-common": "^0.1.3",
     "@backstage/search-common": "^0.2.2",
     "@backstage/types": "^0.1.1",
     "@octokit/graphql": "^4.5.8",

plugins/catalog-backend/src/ingestion/processors/BuiltinKindsEntityProcessor.test.ts

@@ -21,9 +21,9 @@ import {
   GroupEntity,
   ResourceEntity,
   SystemEntity,
-  TemplateEntityV1beta2,
   UserEntity,
 } from '@backstage/catalog-model';
+import { TemplateEntityV1beta2 } from '@backstage/plugin-scaffolder-common';
 import { BuiltinKindsEntityProcessor } from './BuiltinKindsEntityProcessor';
 
 describe('BuiltinKindsEntityProcessor', () => {

plugins/catalog-backend/src/ingestion/processors/BuiltinKindsEntityProcessor.ts

@@ -46,11 +46,13 @@ import {
   resourceEntityV1alpha1Validator,
   SystemEntity,
   systemEntityV1alpha1Validator,
-  TemplateEntityV1beta2,
-  templateEntityV1beta2Validator,
   UserEntity,
   userEntityV1alpha1Validator,
 } from '@backstage/catalog-model';
+import {
+  TemplateEntityV1beta2,
+  templateEntityV1beta2Validator,
+} from '@backstage/plugin-scaffolder-common';
 import * as result from './results';
 import { CatalogProcessor, CatalogProcessorEmit } from './types';
 

plugins/catalog-react/package.json

@@ -59,6 +59,7 @@
     "@backstage/cli": "^0.13.2",
     "@backstage/core-app-api": "^0.5.2",
     "@backstage/plugin-catalog-common": "^0.1.2",
+    "@backstage/plugin-scaffolder-common": "^0.1.3",
     "@backstage/test-utils": "^0.2.4",
     "@testing-library/jest-dom": "^5.10.1",
     "@testing-library/react": "^11.2.5",

plugins/catalog-react/src/filters.test.ts

@@ -14,7 +14,8 @@
  * limitations under the License.
  */
 
-import { Entity, TemplateEntityV1beta2 } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
+import { TemplateEntityV1beta2 } from '@backstage/plugin-scaffolder-common';
 import { EntityTextFilter } from './filters';
 
 const entities: Entity[] = [

plugins/scaffolder-backend/api-report.md

@@ -29,7 +29,7 @@ import { SpawnOptionsWithoutStdio } from 'child_process';
 import { TaskSpec } from '@backstage/plugin-scaffolder-common';
 import { TaskSpecV1beta2 } from '@backstage/plugin-scaffolder-common';
 import { TaskSpecV1beta3 } from '@backstage/plugin-scaffolder-common';
-import { TemplateEntityV1beta2 } from '@backstage/catalog-model';
+import { TemplateEntityV1beta2 } from '@backstage/plugin-scaffolder-common';
 import { TemplateMetadata } from '@backstage/plugin-scaffolder-common';
 import { UrlReader } from '@backstage/backend-common';
 import { Writable } from 'stream';

plugins/scaffolder-backend/src/lib/catalog/CatalogEntityClient.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { TemplateEntityV1beta2 } from '@backstage/catalog-model';
+import { TemplateEntityV1beta2 } from '@backstage/plugin-scaffolder-common';
 import { CatalogApi } from '@backstage/catalog-client';
 import { ConflictError, NotFoundError } from '@backstage/errors';
 

plugins/scaffolder-backend/src/processor/ScaffolderEntitiesProcessor.ts

@@ -21,7 +21,6 @@ import {
   parseEntityRef,
   RELATION_OWNED_BY,
   RELATION_OWNER_OF,
-  entityKindSchemaValidator,
 } from '@backstage/catalog-model';
 import {
   CatalogProcessor,
@@ -30,18 +29,16 @@ import {
 } from '@backstage/plugin-catalog-backend';
 import {
   TemplateEntityV1beta3,
-  templateEntityV1beta3Schema,
+  templateEntityV1beta3Validator,
 } from '@backstage/plugin-scaffolder-common';
 
 /** @public */
 export class ScaffolderEntitiesProcessor implements CatalogProcessor {
-  private readonly validators = [
-    entityKindSchemaValidator(templateEntityV1beta3Schema),
-  ];
+  private readonly validators = [templateEntityV1beta3Validator];
 
   async validateEntityKind(entity: Entity): Promise<boolean> {
     for (const validator of this.validators) {
-      if (validator(entity)) {
+      if (await validator.check(entity)) {
         return true;
       }
     }

plugins/scaffolder-backend/src/scaffolder/index.ts

@@ -13,5 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 export * from './actions';
 export * from './tasks';

plugins/scaffolder-backend/src/service/router.test.ts

@@ -36,7 +36,7 @@ import {
   UrlReaders,
 } from '@backstage/backend-common';
 import { CatalogApi } from '@backstage/catalog-client';
-import { TemplateEntityV1beta2 } from '@backstage/catalog-model';
+import { TemplateEntityV1beta2 } from '@backstage/plugin-scaffolder-common';
 import { ConfigReader } from '@backstage/config';
 import express from 'express';
 import request from 'supertest';

plugins/scaffolder-backend/src/service/router.ts

@@ -20,11 +20,15 @@ import {
   UrlReader,
 } from '@backstage/backend-common';
 import { CatalogApi } from '@backstage/catalog-client';
-import { Entity, TemplateEntityV1beta2 } from '@backstage/catalog-model';
+import { stringifyEntityRef } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import { InputError, NotFoundError } from '@backstage/errors';
 import { ScmIntegrations } from '@backstage/integration';
-import { TemplateEntityV1beta3 } from '@backstage/plugin-scaffolder-common';
+import {
+  TemplateEntityV1beta2,
+  TemplateEntityV1beta3,
+} from '@backstage/plugin-scaffolder-common';
 import express from 'express';
 import Router from 'express-promise-router';
 import { validate } from 'jsonschema';
@@ -190,9 +194,18 @@ export async function createRouter(
       let taskSpec: TaskSpec;
 
       if (isSupportedTemplate(template)) {
+        if (template.apiVersion === 'backstage.io/v1beta2') {
+          logger.warn(
+            `Scaffolding ${stringifyEntityRef(
+              template,
+            )} with deprecated apiVersion ${
+              template.apiVersion
+            }. Please migrate the template to backstage.io/v1beta3. https://backstage.io/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3`,
+          );
+        }
+
         for (const parameters of [template.spec.parameters ?? []].flat()) {
           const result = validate(values, parameters);
-
           if (!result.valid) {
             res.status(400).json({ errors: result.errors });
             return;

plugins/scaffolder-common/api-report.md

@@ -5,13 +5,13 @@
 ```ts
 import { Entity } from '@backstage/catalog-model';
 import { JsonObject } from '@backstage/types';
-import { JSONSchema } from '@backstage/catalog-model';
 import { JsonValue } from '@backstage/types';
+import { KindValidator } from '@backstage/catalog-model';
 
 // @public
 export type TaskSpec = TaskSpecV1beta2 | TaskSpecV1beta3;
 
-// @public
+// @public @deprecated
 export interface TaskSpecV1beta2 {
   // (undocumented)
   apiVersion: 'backstage.io/v1beta2';
@@ -61,7 +61,34 @@ export interface TaskStep {
   name: string;
 }
 
-// @public (undocumented)
+// @public @deprecated
+export interface TemplateEntityV1beta2 extends Entity {
+  // (undocumented)
+  apiVersion: 'backstage.io/v1beta2';
+  // (undocumented)
+  kind: 'Template';
+  // (undocumented)
+  spec: {
+    type: string;
+    parameters?: JsonObject | JsonObject[];
+    steps: Array<{
+      id?: string;
+      name?: string;
+      action: string;
+      input?: JsonObject;
+      if?: string | boolean;
+    }>;
+    output?: {
+      [name: string]: string;
+    };
+    owner?: string;
+  };
+}
+
+// @public @deprecated
+export const templateEntityV1beta2Validator: KindValidator;
+
+// @public
 export interface TemplateEntityV1beta3 extends Entity {
   // (undocumented)
   apiVersion: 'scaffolder.backstage.io/v1beta3';
@@ -85,8 +112,8 @@ export interface TemplateEntityV1beta3 extends Entity {
   };
 }
 
-// @public (undocumented)
-export const templateEntityV1beta3Schema: JSONSchema;
+// @public
+export const templateEntityV1beta3Validator: KindValidator;
 
 // @public
 export type TemplateMetadata = {

plugins/scaffolder-common/src/TaskSpec.ts

@@ -17,7 +17,8 @@
 import { JsonValue, JsonObject } from '@backstage/types';
 
 /**
- * TemplateMetadata
+ * Metadata about the Template that was the originator of a scaffolder task, as
+ * stored in the database.
  *
  * @public
  */
@@ -26,7 +27,7 @@ export type TemplateMetadata = {
 };
 
 /**
- * TaskStep
+ * An individual step of a scaffolder task, as stored in the database.
  *
  * @public
  */
@@ -39,9 +40,12 @@ export interface TaskStep {
 }
 
 /**
- * TaskSpecV1beta2
+ * A scaffolder task as stored in the database, generated from a v1beta2
+ * apiVersion Template.
  *
  * @public
+ * @deprecated Please convert your templates to TaskSpecV1beta3 on apiVersion
+ *             scaffolder.backstage.io/v1beta3
  */
 export interface TaskSpecV1beta2 {
   apiVersion: 'backstage.io/v1beta2';
@@ -53,7 +57,8 @@ export interface TaskSpecV1beta2 {
 }
 
 /**
- * TaskSpecV1beta3
+ * A scaffolder task as stored in the database, generated from a v1beta3
+ * apiVersion Template.
  *
  * @public
  */
@@ -67,7 +72,7 @@ export interface TaskSpecV1beta3 {
 }
 
 /**
- * TaskSpec
+ * A scaffolder task as stored in the database, generated from a Template.
  *
  * @public
  */

plugins/scaffolder-common/src/TemplateEntityV1beta2.ts

@@ -14,15 +14,21 @@
  * limitations under the License.
  */
 
+import {
+  Entity,
+  entityKindSchemaValidator,
+  KindValidator,
+} from '@backstage/catalog-model';
 import { JsonObject } from '@backstage/types';
-import type { Entity } from '../entity/Entity';
-import schema from '../schema/kinds/Template.v1beta2.schema.json';
-import { ajvCompiledJsonSchemaValidator } from './util';
+import schema from './Template.v1beta2.schema.json';
 
 /**
- * Backstage catalog Template kind Entity. Templates are used by the Scaffolder plugin to create new Components.
+ * Backstage catalog Template kind Entity. Templates are used by the Scaffolder
+ * plugin to create new entities, such as Components.
  *
  * @public
+ * @deprecated Please convert your templates to TemplateEntityV1beta3 on
+ *             apiVersion scaffolder.backstage.io/v1beta3
  */
 export interface TemplateEntityV1beta2 extends Entity {
   apiVersion: 'backstage.io/v1beta2';
@@ -42,10 +48,18 @@ export interface TemplateEntityV1beta2 extends Entity {
   };
 }
 
+const validator = entityKindSchemaValidator(schema);
+
 /**
- * {@link KindValidator} for {@link TemplateEntityV1beta2}.
+ * Entity data validator for {@link TemplateEntityV1beta2}.
  *
  * @public
+ * @deprecated Please convert your templates to TemplateEntityV1beta3 on
+ *             apiVersion scaffolder.backstage.io/v1beta3
  */
-export const templateEntityV1beta2Validator =
-  ajvCompiledJsonSchemaValidator(schema);
+export const templateEntityV1beta2Validator: KindValidator = {
+  // TODO(freben): Emulate the old KindValidator until we fix that type
+  async check(data: Entity) {
+    return validator(data) === data;
+  },
+};

plugins/scaffolder-common/src/TemplateEntityV1beta3.ts

@@ -14,10 +14,20 @@
  * limitations under the License.
  */
 
+import {
+  Entity,
+  entityKindSchemaValidator,
+  KindValidator,
+} from '@backstage/catalog-model';
 import { JsonObject } from '@backstage/types';
-import { Entity } from '@backstage/catalog-model';
+import schema from './Template.v1beta3.schema.json';
 
-/** @public */
+/**
+ * Backstage catalog Template kind Entity. Templates are used by the Scaffolder
+ * plugin to create new entities, such as Components.
+ *
+ * @public
+ */
 export interface TemplateEntityV1beta3 extends Entity {
   apiVersion: 'scaffolder.backstage.io/v1beta3';
   kind: 'Template';
@@ -35,3 +45,17 @@ export interface TemplateEntityV1beta3 extends Entity {
     owner?: string;
   };
 }
+
+const validator = entityKindSchemaValidator(schema);
+
+/**
+ * Entity data validator for {@link TemplateEntityV1beta3}.
+ *
+ * @public
+ */
+export const templateEntityV1beta3Validator: KindValidator = {
+  // TODO(freben): Emulate the old KindValidator until we fix that type
+  async check(data: Entity) {
+    return validator(data) === data;
+  },
+};

plugins/scaffolder-common/src/index.ts

@@ -20,15 +20,8 @@
  * @packageDocumentation
  */
 
-import { JSONSchema } from '@backstage/catalog-model';
-import v1beta3Schema from './Template.v1beta3.schema.json';
-
-export type { TemplateEntityV1beta3 } from './TemplateEntityV1beta3';
-
-/** @public */
-export const templateEntityV1beta3Schema: JSONSchema = v1beta3Schema as Omit<
-  JSONSchema,
-  'examples'
->;
-
 export * from './TaskSpec';
+export { templateEntityV1beta2Validator } from './TemplateEntityV1beta2';
+export type { TemplateEntityV1beta2 } from './TemplateEntityV1beta2';
+export { templateEntityV1beta3Validator } from './TemplateEntityV1beta3';
+export type { TemplateEntityV1beta3 } from './TemplateEntityV1beta3';

plugins/scaffolder/api-report.md

@@ -27,7 +27,7 @@ import { ReactNode } from 'react';
 import { RouteRef } from '@backstage/core-plugin-api';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import { TaskSpec } from '@backstage/plugin-scaffolder-common';
-import { TemplateEntityV1beta2 } from '@backstage/catalog-model';
+import { TemplateEntityV1beta2 } from '@backstage/plugin-scaffolder-common';
 
 // Warning: (ae-missing-release-tag) "createScaffolderFieldExtension" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //

plugins/scaffolder/src/components/Router.tsx

@@ -16,7 +16,8 @@
 
 import React, { ComponentType } from 'react';
 import { Routes, Route, useOutlet } from 'react-router';
-import { TemplateEntityV1beta2, Entity } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
+import { TemplateEntityV1beta2 } from '@backstage/plugin-scaffolder-common';
 import { ScaffolderPage } from './ScaffolderPage';
 import { TemplatePage } from './TemplatePage';
 import { TaskPage } from './TaskPage';

plugins/scaffolder/src/components/ScaffolderPage/ScaffolderPage.tsx

@@ -23,7 +23,8 @@ import {
   Page,
   SupportButton,
 } from '@backstage/core-components';
-import { TemplateEntityV1beta2, Entity } from '@backstage/catalog-model';
+import { Entity } from '@backstage/catalog-model';
+import { TemplateEntityV1beta2 } from '@backstage/plugin-scaffolder-common';
 import { useRouteRef } from '@backstage/core-plugin-api';
 import {
   EntityKindPicker,

plugins/scaffolder/src/components/TemplateCard/TemplateCard.tsx

@@ -13,11 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import {
-  Entity,
-  RELATION_OWNED_BY,
-  TemplateEntityV1beta2,
-} from '@backstage/catalog-model';
+import { Entity, RELATION_OWNED_BY } from '@backstage/catalog-model';
+import { TemplateEntityV1beta2 } from '@backstage/plugin-scaffolder-common';
 import {
   ScmIntegrationIcon,
   scmIntegrationsApiRef,
@@ -123,7 +120,8 @@ const DeprecationWarning = () => {
 
   const Title = (
     <Typography style={{ padding: 10, maxWidth: 300 }}>
-      This template syntax is deprecated. Click for more info.
+      This template uses a syntax that has been deprecated, and should be
+      migrated to a newer syntax. Click for more info.
     </Typography>
   );
 
@@ -131,7 +129,7 @@ const DeprecationWarning = () => {
     <div className={styles.deprecationIcon}>
       <Tooltip title={Title}>
         <Link
-          href="https://backstage.io/docs/features/software-templates/migrating-from-v1alpha1-to-v1beta2"
+          href="https://backstage.io/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3"
           className={styles.link}
         >
           <WarningIcon />

plugins/scaffolder/src/components/TemplateList/TemplateList.tsx

@@ -15,11 +15,8 @@
  */
 
 import React, { ComponentType } from 'react';
-import {
-  Entity,
-  stringifyEntityRef,
-  TemplateEntityV1beta2,
-} from '@backstage/catalog-model';
+import { Entity, stringifyEntityRef } from '@backstage/catalog-model';
+import { TemplateEntityV1beta2 } from '@backstage/plugin-scaffolder-common';
 import {
   Content,
   ContentHeader,
@@ -90,6 +87,7 @@ export const TemplateList = ({
               <Card
                 key={stringifyEntityRef(template)}
                 template={template as TemplateEntityV1beta2}
+                deprecated={template.apiVersion === 'backstage.io/v1beta2'}
               />
             ))}
         </ItemCardGrid>