diff --git a/.changeset/wise-cooks-admire.md b/.changeset/wise-cooks-admire.md new file mode 100644 index 0000000000..65f33ffff0 --- /dev/null +++ b/.changeset/wise-cooks-admire.md @@ -0,0 +1,21 @@ +--- +'@backstage/catalog-model': patch +--- + +Added `alpha` release stage type declarations, accessible via `@backstage/catalog-model/alpha`. + +**BREAKING**: The experimental entity `status` field was removed from the base `Entity` type and is now only available on the `AlphaEntity` type from the alpha release stage, along with all accompanying types that were previously marked as `UNSTABLE_`. + +For example, the following import: + +```ts +import { UNSTABLE_EntityStatusItem } from '@backstage/catalog-model'; +``` + +Becomes this: + +```ts +import { EntityStatusItem } from '@backstage/catalog-model/alpha'; +``` + +Note that exports that are only available from the alpha release stage are considered unstable and do not adhere to the semantic versioning of the package. diff --git a/packages/catalog-model/api-report.md b/packages/catalog-model/api-report.md index 9c0c33fa0e..59eeb98924 100644 --- a/packages/catalog-model/api-report.md +++ b/packages/catalog-model/api-report.md @@ -9,6 +9,11 @@ import { JsonValue } from '@backstage/types'; import { SerializedError } from '@backstage/errors'; import * as yup from 'yup'; +// @alpha +export interface AlphaEntity extends Entity { + status?: EntityStatus; +} + // @public @deprecated export const analyzeLocationSchema: yup.SchemaOf<{ location: LocationSpec; @@ -116,7 +121,6 @@ export type Entity = { metadata: EntityMeta; spec?: JsonObject; relations?: EntityRelation[]; - status?: UNSTABLE_EntityStatus; }; // @public @@ -225,6 +229,22 @@ export function entitySchemaValidator( schema?: unknown, ): (data: unknown) => T; +// @alpha +export type EntityStatus = { + items?: EntityStatusItem[]; +}; + +// @alpha +export type EntityStatusItem = { + type: string; + level: EntityStatusLevel; + message: string; + error?: SerializedError; +}; + +// @alpha +export type EntityStatusLevel = 'info' | 'warning' | 'error'; + // @public export class FieldFormatEntityPolicy implements EntityPolicy { constructor(validators?: Validators); @@ -550,22 +570,6 @@ export interface TemplateEntityV1beta2 extends Entity { // @public export const templateEntityV1beta2Validator: KindValidator; -// @alpha -export type UNSTABLE_EntityStatus = { - items?: UNSTABLE_EntityStatusItem[]; -}; - -// @alpha -export type UNSTABLE_EntityStatusItem = { - type: string; - level: UNSTABLE_EntityStatusLevel; - message: string; - error?: SerializedError; -}; - -// @alpha -export type UNSTABLE_EntityStatusLevel = 'info' | 'warning' | 'error'; - // @public interface UserEntityV1alpha1 extends Entity { // (undocumented) @@ -603,8 +607,4 @@ export type Validators = { // @public export const VIEW_URL_ANNOTATION = 'backstage.io/view-url'; - -// Warnings were encountered during analysis: -// -// src/entity/Entity.d.ts:41:5 - (ae-incompatible-release-tags) The symbol "status" is marked as @public, but its signature references "UNSTABLE_EntityStatus" which is marked as @alpha ``` diff --git a/packages/catalog-model/package.json b/packages/catalog-model/package.json index c1a13d00f2..bb93259a9f 100644 --- a/packages/catalog-model/package.json +++ b/packages/catalog-model/package.json @@ -10,7 +10,8 @@ "access": "public", "main": "dist/index.cjs.js", "module": "dist/index.esm.js", - "types": "dist/index.d.ts" + "types": "dist/index.d.ts", + "alphaTypes": "dist/index.alpha.d.ts" }, "homepage": "https://backstage.io", "repository": { @@ -22,7 +23,7 @@ "backstage" ], "scripts": { - "build": "backstage-cli build", + "build": "backstage-cli build --experimental-type-build", "lint": "backstage-cli lint", "test": "backstage-cli test", "prepack": "backstage-cli prepack", @@ -48,6 +49,7 @@ "yaml": "^1.9.2" }, "files": [ - "dist" + "dist", + "alpha" ] } diff --git a/packages/catalog-model/src/entity/Entity.ts b/packages/catalog-model/src/entity/Entity.ts index 9d65d3e8f3..f56774025c 100644 --- a/packages/catalog-model/src/entity/Entity.ts +++ b/packages/catalog-model/src/entity/Entity.ts @@ -16,7 +16,7 @@ import { JsonObject } from '@backstage/types'; import { EntityName } from '../types'; -import { UNSTABLE_EntityStatus } from './EntityStatus'; +import { EntityStatus } from './EntityStatus'; /** * The parts of the format that's common to all versions/kinds of entity. @@ -53,15 +53,26 @@ export type Entity = { * The relations that this entity has with other entities. */ relations?: EntityRelation[]; +}; +/** + * A version of the {@link Entity} type that contains unstable alpha fields. + * + * @remarks + * + * Available via the `@backstage/catalog-model/alpha` import. + * + * @alpha + */ +export interface AlphaEntity extends Entity { /** * The current status of the entity, as claimed by various sources. * * The keys are implementation defined and the values can be any JSON object * with semantics that match that implementation. */ - status?: UNSTABLE_EntityStatus; -}; + status?: EntityStatus; +} /** * Metadata fields common to all versions/kinds of entity. diff --git a/packages/catalog-model/src/entity/EntityStatus.ts b/packages/catalog-model/src/entity/EntityStatus.ts index 8f79fbd615..5ffd8a8e06 100644 --- a/packages/catalog-model/src/entity/EntityStatus.ts +++ b/packages/catalog-model/src/entity/EntityStatus.ts @@ -21,18 +21,18 @@ import { SerializedError } from '@backstage/errors'; * * @alpha */ -export type UNSTABLE_EntityStatus = { +export type EntityStatus = { /** * Specific status item on a well known format. */ - items?: UNSTABLE_EntityStatusItem[]; + items?: EntityStatusItem[]; }; /** * A specific status item on a well known format. * @alpha */ -export type UNSTABLE_EntityStatusItem = { +export type EntityStatusItem = { /** * The type of status as a unique key per source. */ @@ -43,7 +43,7 @@ export type UNSTABLE_EntityStatusItem = { * entry may apply to a different, newer version of the data than what is * being returned in the catalog response. */ - level: UNSTABLE_EntityStatusLevel; + level: EntityStatusLevel; /** * A brief message describing the status, intended for human consumption. */ @@ -58,7 +58,7 @@ export type UNSTABLE_EntityStatusItem = { * Each entity status item has a level, describing its severity. * @alpha */ -export type UNSTABLE_EntityStatusLevel = +export type EntityStatusLevel = | 'info' // Only informative data | 'warning' // Warnings were found | 'error'; // Errors were found diff --git a/packages/catalog-model/src/entity/index.ts b/packages/catalog-model/src/entity/index.ts index eac55ea325..ce1e76a20b 100644 --- a/packages/catalog-model/src/entity/index.ts +++ b/packages/catalog-model/src/entity/index.ts @@ -21,6 +21,7 @@ export { VIEW_URL_ANNOTATION, } from './constants'; export type { + AlphaEntity, Entity, EntityLink, EntityMeta, @@ -29,9 +30,9 @@ export type { } from './Entity'; export type { EntityEnvelope } from './EntityEnvelope'; export type { - UNSTABLE_EntityStatus, - UNSTABLE_EntityStatusItem, - UNSTABLE_EntityStatusLevel, + EntityStatus, + EntityStatusItem, + EntityStatusLevel, } from './EntityStatus'; export * from './policies'; export { diff --git a/packages/catalog-model/src/entity/util.ts b/packages/catalog-model/src/entity/util.ts index ce6415afde..4506a8d852 100644 --- a/packages/catalog-model/src/entity/util.ts +++ b/packages/catalog-model/src/entity/util.ts @@ -16,7 +16,7 @@ import lodash from 'lodash'; import { v4 as uuidv4 } from 'uuid'; -import { Entity } from './Entity'; +import { Entity, AlphaEntity } from './Entity'; /** * Generates a new random UID for an entity. @@ -89,9 +89,9 @@ export function entityHasChanges(previous: Entity, next: Entity): boolean { // Remove things that we explicitly do not compare delete e1.relations; - delete e1.status; + delete (e1 as AlphaEntity).status; delete e2.relations; - delete e2.status; + delete (e2 as AlphaEntity).status; return !lodash.isEqual(e1, e2); }