diff --git a/.changeset/small-hornets-dress.md b/.changeset/small-hornets-dress.md new file mode 100644 index 0000000000..474c3011bd --- /dev/null +++ b/.changeset/small-hornets-dress.md @@ -0,0 +1,10 @@ +--- +'@backstage/plugin-catalog-backend': patch +'@backstage/plugin-catalog-common': patch +--- + +**DEPRECATION**: Moved the `CatalogEntityDocument` to `@backstage/plugin-catalog-common` and deprecated the export from `@backstage/plugin-catalog-backend`. + +A new `type` field has also been added to `CatalogEntityDocument` as a replacement for `componentType`, which is now deprecated. Both fields are still present and should be set to the same value in order to avoid issues with indexing. + +Any search customizations need to be updated to use this new `type` field instead, including any custom frontend filters, custom frontend result components, custom search decorators, or non-default Catalog collator implementations. diff --git a/plugins/catalog-backend/api-report.md b/plugins/catalog-backend/api-report.md index a1125ec529..0d9f306009 100644 --- a/plugins/catalog-backend/api-report.md +++ b/plugins/catalog-backend/api-report.md @@ -7,6 +7,7 @@ import { BitbucketIntegration } from '@backstage/integration'; import { CatalogApi } from '@backstage/catalog-client'; +import { CatalogEntityDocument as CatalogEntityDocument_2 } from '@backstage/plugin-catalog-common'; import { CompoundEntityRef } from '@backstage/catalog-model'; import { ConditionalPolicyDecision } from '@backstage/plugin-permission-node'; import { Conditions } from '@backstage/plugin-permission-node'; @@ -18,7 +19,6 @@ import express from 'express'; import { GetEntitiesRequest } from '@backstage/catalog-client'; import { GithubCredentialsProvider } from '@backstage/integration'; import { GitHubIntegrationConfig } from '@backstage/integration'; -import { IndexableDocument } from '@backstage/search-common'; import { JsonObject } from '@backstage/types'; import { JsonValue } from '@backstage/types'; import { Location as Location_2 } from '@backstage/catalog-client'; @@ -254,19 +254,8 @@ export const catalogConditions: Conditions<{ >; }>; -// @public (undocumented) -export interface CatalogEntityDocument extends IndexableDocument { - // (undocumented) - componentType: string; - // (undocumented) - kind: string; - // (undocumented) - lifecycle: string; - // (undocumented) - namespace: string; - // (undocumented) - owner: string; -} +// @public @deprecated (undocumented) +export type CatalogEntityDocument = CatalogEntityDocument_2; // @public (undocumented) export type CatalogEnvironment = { @@ -447,7 +436,7 @@ export class DefaultCatalogCollator { // (undocumented) protected discovery: PluginEndpointDiscovery; // (undocumented) - execute(): Promise; + execute(): Promise; // (undocumented) protected filter?: GetEntitiesRequest['filter']; // (undocumented) diff --git a/plugins/catalog-backend/src/search/DefaultCatalogCollator.ts b/plugins/catalog-backend/src/search/DefaultCatalogCollator.ts index c59318d0af..ac9a33bf62 100644 --- a/plugins/catalog-backend/src/search/DefaultCatalogCollator.ts +++ b/plugins/catalog-backend/src/search/DefaultCatalogCollator.ts @@ -29,8 +29,10 @@ import { CatalogClient, GetEntitiesRequest, } from '@backstage/catalog-client'; -import { catalogEntityReadPermission } from '@backstage/plugin-catalog-common'; -import { CatalogEntityDocument } from './DefaultCatalogCollatorFactory'; +import { + catalogEntityReadPermission, + CatalogEntityDocument, +} from '@backstage/plugin-catalog-common'; /** * @public @@ -125,6 +127,7 @@ export class DefaultCatalogCollator { }), text: this.getDocumentText(entity), componentType: entity.spec?.type?.toString() || 'other', + type: entity.spec?.type?.toString() || 'other', namespace: entity.metadata.namespace || 'default', kind: entity.kind, lifecycle: (entity.spec?.lifecycle as string) || '', diff --git a/plugins/catalog-backend/src/search/DefaultCatalogCollatorFactory.ts b/plugins/catalog-backend/src/search/DefaultCatalogCollatorFactory.ts index 99377b2ca0..440a8c8ebb 100644 --- a/plugins/catalog-backend/src/search/DefaultCatalogCollatorFactory.ts +++ b/plugins/catalog-backend/src/search/DefaultCatalogCollatorFactory.ts @@ -29,22 +29,13 @@ import { UserEntity, } from '@backstage/catalog-model'; import { Config } from '@backstage/config'; +import { DocumentCollatorFactory } from '@backstage/search-common'; import { - DocumentCollatorFactory, - IndexableDocument, -} from '@backstage/search-common'; -import { catalogEntityReadPermission } from '@backstage/plugin-catalog-common'; + catalogEntityReadPermission, + CatalogEntityDocument, +} from '@backstage/plugin-catalog-common'; import { Readable } from 'stream'; -/** @public */ -export interface CatalogEntityDocument extends IndexableDocument { - componentType: string; - namespace: string; - kind: string; - lifecycle: string; - owner: string; -} - /** @public */ export type DefaultCatalogCollatorFactoryOptions = { discovery: PluginEndpointDiscovery; @@ -159,6 +150,7 @@ export class DefaultCatalogCollatorFactory implements DocumentCollatorFactory { }), text: this.getDocumentText(entity), componentType: entity.spec?.type?.toString() || 'other', + type: entity.spec?.type?.toString() || 'other', namespace: entity.metadata.namespace || 'default', kind: entity.kind, lifecycle: (entity.spec?.lifecycle as string) || '', diff --git a/plugins/catalog-backend/src/search/index.ts b/plugins/catalog-backend/src/search/index.ts index 93ff0b8b32..eb5b1e7c22 100644 --- a/plugins/catalog-backend/src/search/index.ts +++ b/plugins/catalog-backend/src/search/index.ts @@ -16,7 +16,14 @@ export { DefaultCatalogCollatorFactory } from './DefaultCatalogCollatorFactory'; export type { DefaultCatalogCollatorFactoryOptions } from './DefaultCatalogCollatorFactory'; -export type { CatalogEntityDocument } from './DefaultCatalogCollatorFactory'; + +import { CatalogEntityDocument as CatalogEntityDocumentType } from '@backstage/plugin-catalog-common'; + +/** + * @deprecated import from `@backstage/plugin-catalog-common` instead + * @public + */ +export type CatalogEntityDocument = CatalogEntityDocumentType; /** * todo(backstage/techdocs-core): stop exporting this in a future release. diff --git a/plugins/catalog-common/api-report.md b/plugins/catalog-common/api-report.md index 57f8c3983e..a73cae9994 100644 --- a/plugins/catalog-common/api-report.md +++ b/plugins/catalog-common/api-report.md @@ -3,6 +3,7 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts +import { IndexableDocument } from '@backstage/search-common'; import { Permission } from '@backstage/plugin-permission-common'; // @alpha @@ -11,6 +12,22 @@ export const catalogEntityCreatePermission: Permission; // @alpha export const catalogEntityDeletePermission: Permission; +// @public +export interface CatalogEntityDocument extends IndexableDocument { + // @deprecated (undocumented) + componentType: string; + // (undocumented) + kind: string; + // (undocumented) + lifecycle: string; + // (undocumented) + namespace: string; + // (undocumented) + owner: string; + // (undocumented) + type: string; +} + // @alpha export const catalogEntityReadPermission: Permission; diff --git a/plugins/catalog-common/package.json b/plugins/catalog-common/package.json index acf4ed4aaa..bc0d3750ba 100644 --- a/plugins/catalog-common/package.json +++ b/plugins/catalog-common/package.json @@ -34,7 +34,8 @@ "clean": "backstage-cli package clean" }, "dependencies": { - "@backstage/plugin-permission-common": "^0.5.1" + "@backstage/plugin-permission-common": "^0.5.1", + "@backstage/search-common": "^0.2.4" }, "devDependencies": { "@backstage/cli": "^0.14.0" diff --git a/plugins/catalog-common/src/index.ts b/plugins/catalog-common/src/index.ts index 9eddf37452..08184eb871 100644 --- a/plugins/catalog-common/src/index.ts +++ b/plugins/catalog-common/src/index.ts @@ -31,3 +31,5 @@ export { catalogLocationCreatePermission, catalogLocationDeletePermission, } from './permissions'; + +export * from './search'; diff --git a/plugins/catalog-common/src/search/CatalogEntityDocument.ts b/plugins/catalog-common/src/search/CatalogEntityDocument.ts new file mode 100644 index 0000000000..834dde2568 --- /dev/null +++ b/plugins/catalog-common/src/search/CatalogEntityDocument.ts @@ -0,0 +1,31 @@ +/* + * Copyright 2022 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +import { IndexableDocument } from '@backstage/search-common'; + +/** + * The Document format for an Entity in the Catalog for search + * + * @public + */ +export interface CatalogEntityDocument extends IndexableDocument { + /** @deprecated `componentType` is being renamed to `type`. During the transition both of these fields should be set to the same value, in order to avoid issues with indexing. */ + componentType: string; + type: string; + namespace: string; + kind: string; + lifecycle: string; + owner: string; +} diff --git a/plugins/catalog-common/src/search/index.ts b/plugins/catalog-common/src/search/index.ts new file mode 100644 index 0000000000..82e713aba0 --- /dev/null +++ b/plugins/catalog-common/src/search/index.ts @@ -0,0 +1,16 @@ +/* + * Copyright 2022 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +export type { CatalogEntityDocument } from './CatalogEntityDocument';