From 40808de76787f4564ee3fa47d72756b04c61ec8e Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Wed, 5 Jun 2024 17:30:20 +0900 Subject: [PATCH 01/11] Add spec.type to Domain model Signed-off-by: Joe Van Alstyne --- .../examples/domains/artists-domain.yaml | 1 + .../examples/domains/playback-domain.yaml | 1 + .../src/kinds/DomainEntityV1alpha1.test.ts | 11 +++++++++++ .../catalog-model/src/kinds/DomainEntityV1alpha1.ts | 1 + .../src/schema/kinds/Domain.v1alpha1.schema.json | 9 ++++++++- 5 files changed, 22 insertions(+), 1 deletion(-) diff --git a/packages/catalog-model/examples/domains/artists-domain.yaml b/packages/catalog-model/examples/domains/artists-domain.yaml index 598f8500aa..02370d9a14 100644 --- a/packages/catalog-model/examples/domains/artists-domain.yaml +++ b/packages/catalog-model/examples/domains/artists-domain.yaml @@ -13,3 +13,4 @@ metadata: spec: owner: team-a subdomainOf: audio + type: product-group diff --git a/packages/catalog-model/examples/domains/playback-domain.yaml b/packages/catalog-model/examples/domains/playback-domain.yaml index 58b5afe56e..e058ebf0a2 100644 --- a/packages/catalog-model/examples/domains/playback-domain.yaml +++ b/packages/catalog-model/examples/domains/playback-domain.yaml @@ -6,3 +6,4 @@ metadata: spec: owner: user:frank.tiernan subdomainOf: audio + type: product-group diff --git a/packages/catalog-model/src/kinds/DomainEntityV1alpha1.test.ts b/packages/catalog-model/src/kinds/DomainEntityV1alpha1.test.ts index 3c1e7f0a6d..181a696192 100644 --- a/packages/catalog-model/src/kinds/DomainEntityV1alpha1.test.ts +++ b/packages/catalog-model/src/kinds/DomainEntityV1alpha1.test.ts @@ -32,6 +32,7 @@ describe('DomainV1alpha1Validator', () => { spec: { owner: 'me', subdomainOf: 'parent-domain', + type: 'domain-type', }, }; }); @@ -84,4 +85,14 @@ describe('DomainV1alpha1Validator', () => { (entity as any).spec.subdomainOf = ''; await expect(validator.check(entity)).rejects.toThrow(/subdomainOf/); }); + + it('accepts missing type', async () => { + delete (entity as any).spec.type; + await expect(validator.check(entity)).resolves.toBe(true); + }); + + it('rejects empty type', async () => { + (entity as any).spec.type = ''; + await expect(validator.check(entity)).rejects.toThrow(/type/); + }); }); diff --git a/packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts b/packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts index 1fe3dfb522..765329abb4 100644 --- a/packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts @@ -33,6 +33,7 @@ export interface DomainEntityV1alpha1 extends Entity { spec: { owner: string; subdomainOf?: string; + type?: string; }; } diff --git a/packages/catalog-model/src/schema/kinds/Domain.v1alpha1.schema.json b/packages/catalog-model/src/schema/kinds/Domain.v1alpha1.schema.json index 7d0d7e25ff..e4a6c29dd1 100644 --- a/packages/catalog-model/src/schema/kinds/Domain.v1alpha1.schema.json +++ b/packages/catalog-model/src/schema/kinds/Domain.v1alpha1.schema.json @@ -12,7 +12,8 @@ }, "spec": { "owner": "artist-relations-team", - "subdomainOf": "audio" + "subdomainOf": "audio", + "type": "product-group" } } ], @@ -45,6 +46,12 @@ "description": "An entity reference to another domain of which the domain is a part.", "examples": ["audio"], "minLength": 1 + }, + "type": { + "type": "string", + "description": "The type of domain. There is currently no enforced set of values for this field, so it is left up to the adopting organization to choose a nomenclature that matches their catalog hierarchy.", + "examples": ["product-group", "bundle"], + "minLength": 1 } } } From 218abd5473183912064c5b86cccbd3c92147fe01 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Wed, 5 Jun 2024 17:34:36 +0900 Subject: [PATCH 02/11] Update api-report.md Signed-off-by: Joe Van Alstyne --- packages/catalog-model/api-report.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/catalog-model/api-report.md b/packages/catalog-model/api-report.md index 2d91fa44a5..7b06e80fc5 100644 --- a/packages/catalog-model/api-report.md +++ b/packages/catalog-model/api-report.md @@ -123,6 +123,7 @@ interface DomainEntityV1alpha1 extends Entity { spec: { owner: string; subdomainOf?: string; + type?: string; }; } export { DomainEntityV1alpha1 as DomainEntity }; From 34fa803f2961136a6ab367c8e362f34f86404bc3 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Wed, 5 Jun 2024 17:36:17 +0900 Subject: [PATCH 03/11] Add changeset Signed-off-by: Joe Van Alstyne --- .changeset/young-birds-push.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/young-birds-push.md diff --git a/.changeset/young-birds-push.md b/.changeset/young-birds-push.md new file mode 100644 index 0000000000..5b8ab3a81f --- /dev/null +++ b/.changeset/young-birds-push.md @@ -0,0 +1,5 @@ +--- +'@backstage/catalog-model': minor +--- + +Introduce an optional spec.type attribute on the Domain entity kind From 4e392ebdc49d3afbfa35bd767757bdcf839516d8 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Wed, 5 Jun 2024 17:42:20 +0900 Subject: [PATCH 04/11] Update documentation Signed-off-by: Joe Van Alstyne --- docs/features/software-catalog/descriptor-format.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 416eb27fbd..1287a0780e 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -1303,6 +1303,18 @@ which the domain is a part, e.g. `audio`. This field is optional. | --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | | [`Domain`](#kind-domain) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) | +### `spec.type` [optional] + +The type of domain. There is currently no enforced set of values for this field, +so it is left up to the adopting organization to choose a nomenclature that +matches their catalog hierarchy. This field is optional. + +Some common values for this field could be: + +- `product-area` +- `product-group` +- `bundle` + ## Kind: Location Describes the following entity kind: From ccb514f24d0c0d0b7e0d5d14bc33c94583ff68e4 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Mon, 10 Jun 2024 18:54:32 +0900 Subject: [PATCH 05/11] Add spec.type to Sytem model Signed-off-by: Joe Van Alstyne --- .../systems/artist-engagement-portal-system.yaml | 1 + .../examples/systems/audio-playback-system.yaml | 1 + .../examples/systems/podcast-system.yaml | 1 + .../src/kinds/SystemEntityV1alpha1.test.ts | 11 +++++++++++ .../catalog-model/src/kinds/SystemEntityV1alpha1.ts | 1 + .../src/schema/kinds/System.v1alpha1.schema.json | 9 ++++++++- 6 files changed, 23 insertions(+), 1 deletion(-) diff --git a/packages/catalog-model/examples/systems/artist-engagement-portal-system.yaml b/packages/catalog-model/examples/systems/artist-engagement-portal-system.yaml index 8de3c00880..17fe21ba69 100644 --- a/packages/catalog-model/examples/systems/artist-engagement-portal-system.yaml +++ b/packages/catalog-model/examples/systems/artist-engagement-portal-system.yaml @@ -8,3 +8,4 @@ metadata: spec: owner: team-a domain: artists + type: service diff --git a/packages/catalog-model/examples/systems/audio-playback-system.yaml b/packages/catalog-model/examples/systems/audio-playback-system.yaml index 7430ae2ff5..f1edb7f17d 100644 --- a/packages/catalog-model/examples/systems/audio-playback-system.yaml +++ b/packages/catalog-model/examples/systems/audio-playback-system.yaml @@ -6,3 +6,4 @@ metadata: spec: owner: team-c domain: playback + type: feature-set diff --git a/packages/catalog-model/examples/systems/podcast-system.yaml b/packages/catalog-model/examples/systems/podcast-system.yaml index 47a2f7ac9f..77f53925c1 100644 --- a/packages/catalog-model/examples/systems/podcast-system.yaml +++ b/packages/catalog-model/examples/systems/podcast-system.yaml @@ -6,3 +6,4 @@ metadata: spec: owner: team-b domain: playback + type: feature-set diff --git a/packages/catalog-model/src/kinds/SystemEntityV1alpha1.test.ts b/packages/catalog-model/src/kinds/SystemEntityV1alpha1.test.ts index fd78633a89..915f455e79 100644 --- a/packages/catalog-model/src/kinds/SystemEntityV1alpha1.test.ts +++ b/packages/catalog-model/src/kinds/SystemEntityV1alpha1.test.ts @@ -32,6 +32,7 @@ describe('SystemV1alpha1Validator', () => { spec: { owner: 'me', domain: 'domain', + type: 'system-type', }, }; }); @@ -84,4 +85,14 @@ describe('SystemV1alpha1Validator', () => { (entity as any).spec.domain = ''; await expect(validator.check(entity)).rejects.toThrow(/domain/); }); + + it('accepts missing type', async () => { + delete (entity as any).spec.type; + await expect(validator.check(entity)).resolves.toBe(true); + }); + + it('rejects empty type', async () => { + (entity as any).spec.type = ''; + await expect(validator.check(entity)).rejects.toThrow(/type/); + }); }); diff --git a/packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts b/packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts index 88d405ec5b..37ecee8f6c 100644 --- a/packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts @@ -33,6 +33,7 @@ export interface SystemEntityV1alpha1 extends Entity { spec: { owner: string; domain?: string; + type?: string; }; } diff --git a/packages/catalog-model/src/schema/kinds/System.v1alpha1.schema.json b/packages/catalog-model/src/schema/kinds/System.v1alpha1.schema.json index 2cdbc37076..f91fe751dc 100644 --- a/packages/catalog-model/src/schema/kinds/System.v1alpha1.schema.json +++ b/packages/catalog-model/src/schema/kinds/System.v1alpha1.schema.json @@ -12,7 +12,8 @@ }, "spec": { "owner": "artist-relations-team", - "domain": "artists" + "domain": "artists", + "type": "service" } } ], @@ -45,6 +46,12 @@ "description": "An entity reference to the domain that the system belongs to.", "examples": ["artists"], "minLength": 1 + }, + "type": { + "type": "string", + "description": "The type of system. There is currently no enforced set of values for this field, so it is left up to the adopting organization to choose a nomenclature that matches their catalog hierarchy.", + "examples": ["product", "service", "feature-set"], + "minLength": 1 } } } From 2d6003457426d4a9caf8d12df421e9865bb6f482 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Mon, 10 Jun 2024 18:58:00 +0900 Subject: [PATCH 06/11] Update documentation Signed-off-by: Joe Van Alstyne --- docs/features/software-catalog/descriptor-format.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 1287a0780e..57c2283586 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -1243,6 +1243,18 @@ system belongs to, e.g. `artists`. This field is optional. | --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------- | | [`Domain`](#kind-domain) (default) | Same as this entity, typically `default` | [`partOf`, and reverse `hasPart`](well-known-relations.md#partof-and-haspart) | +### `spec.type` [optional] + +The type of system. There is currently no enforced set of values for this field, +so it is left up to the adopting organization to choose a nomenclature that +matches their catalog hierarchy. This field is optional. + +Some common values for this field could be: + +- `product` +- `service` +- `feature-set` + ## Kind: Domain Describes the following entity kind: From 55a5ef2c3212c2aca2221cc94716f1b18a9d18c2 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Mon, 10 Jun 2024 19:03:17 +0900 Subject: [PATCH 07/11] Update changeset Signed-off-by: Joe Van Alstyne --- .changeset/young-birds-push.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/young-birds-push.md b/.changeset/young-birds-push.md index 5b8ab3a81f..54afa48aaf 100644 --- a/.changeset/young-birds-push.md +++ b/.changeset/young-birds-push.md @@ -2,4 +2,4 @@ '@backstage/catalog-model': minor --- -Introduce an optional spec.type attribute on the Domain entity kind +Introduce an optional spec.type attribute on the Domain and System entity kinds From ef71b00bbe0b2878379c73d67747751961e7cba2 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Mon, 10 Jun 2024 19:09:37 +0900 Subject: [PATCH 08/11] Update api-report.md Signed-off-by: Joe Van Alstyne --- packages/catalog-model/api-report.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/catalog-model/api-report.md b/packages/catalog-model/api-report.md index 7b06e80fc5..de941e2502 100644 --- a/packages/catalog-model/api-report.md +++ b/packages/catalog-model/api-report.md @@ -455,6 +455,7 @@ interface SystemEntityV1alpha1 extends Entity { spec: { owner: string; domain?: string; + type?: string; }; } export { SystemEntityV1alpha1 as SystemEntity }; From 1a0d955bb526e47ef8d635e267adb56868207e25 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Fri, 9 Aug 2024 18:17:19 +0900 Subject: [PATCH 09/11] Add test to DomainEntityV1alpha1.test.ts Signed-off-by: Joe Van Alstyne --- .../catalog-model/src/kinds/DomainEntityV1alpha1.test.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/catalog-model/src/kinds/DomainEntityV1alpha1.test.ts b/packages/catalog-model/src/kinds/DomainEntityV1alpha1.test.ts index 181a696192..ce35441fc8 100644 --- a/packages/catalog-model/src/kinds/DomainEntityV1alpha1.test.ts +++ b/packages/catalog-model/src/kinds/DomainEntityV1alpha1.test.ts @@ -95,4 +95,9 @@ describe('DomainV1alpha1Validator', () => { (entity as any).spec.type = ''; await expect(validator.check(entity)).rejects.toThrow(/type/); }); + + it('rejects wrong type', async () => { + (entity as any).spec.type = 7; + await expect(validator.check(entity)).rejects.toThrow(/type/); + }); }); From 33489f73abe9032304c37c5777fbb5e91bba6b53 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Fri, 9 Aug 2024 18:17:33 +0900 Subject: [PATCH 10/11] Add test to SystemEntityV1alpha1.test.ts Signed-off-by: Joe Van Alstyne --- .../catalog-model/src/kinds/SystemEntityV1alpha1.test.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/catalog-model/src/kinds/SystemEntityV1alpha1.test.ts b/packages/catalog-model/src/kinds/SystemEntityV1alpha1.test.ts index 915f455e79..6ea295f190 100644 --- a/packages/catalog-model/src/kinds/SystemEntityV1alpha1.test.ts +++ b/packages/catalog-model/src/kinds/SystemEntityV1alpha1.test.ts @@ -95,4 +95,9 @@ describe('SystemV1alpha1Validator', () => { (entity as any).spec.type = ''; await expect(validator.check(entity)).rejects.toThrow(/type/); }); + + it('rejects wrong type', async () => { + (entity as any).spec.type = 7; + await expect(validator.check(entity)).rejects.toThrow(/type/); + }); }); From 30e13a6b822d0c9db7bec55411b0e7cb43d9b9c6 Mon Sep 17 00:00:00 2001 From: Joe Van Alstyne Date: Fri, 9 Aug 2024 18:25:16 +0900 Subject: [PATCH 11/11] Fix test order in DomainEntityV1alpha1.test.ts, SystemEntityV1alpha1.test.ts Signed-off-by: Joe Van Alstyne --- .../src/kinds/DomainEntityV1alpha1.test.ts | 10 +++++----- .../src/kinds/SystemEntityV1alpha1.test.ts | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/packages/catalog-model/src/kinds/DomainEntityV1alpha1.test.ts b/packages/catalog-model/src/kinds/DomainEntityV1alpha1.test.ts index ce35441fc8..61408b7e80 100644 --- a/packages/catalog-model/src/kinds/DomainEntityV1alpha1.test.ts +++ b/packages/catalog-model/src/kinds/DomainEntityV1alpha1.test.ts @@ -91,13 +91,13 @@ describe('DomainV1alpha1Validator', () => { await expect(validator.check(entity)).resolves.toBe(true); }); - it('rejects empty type', async () => { - (entity as any).spec.type = ''; - await expect(validator.check(entity)).rejects.toThrow(/type/); - }); - it('rejects wrong type', async () => { (entity as any).spec.type = 7; await expect(validator.check(entity)).rejects.toThrow(/type/); }); + + it('rejects empty type', async () => { + (entity as any).spec.type = ''; + await expect(validator.check(entity)).rejects.toThrow(/type/); + }); }); diff --git a/packages/catalog-model/src/kinds/SystemEntityV1alpha1.test.ts b/packages/catalog-model/src/kinds/SystemEntityV1alpha1.test.ts index 6ea295f190..828fe7a648 100644 --- a/packages/catalog-model/src/kinds/SystemEntityV1alpha1.test.ts +++ b/packages/catalog-model/src/kinds/SystemEntityV1alpha1.test.ts @@ -91,13 +91,13 @@ describe('SystemV1alpha1Validator', () => { await expect(validator.check(entity)).resolves.toBe(true); }); - it('rejects empty type', async () => { - (entity as any).spec.type = ''; - await expect(validator.check(entity)).rejects.toThrow(/type/); - }); - it('rejects wrong type', async () => { (entity as any).spec.type = 7; await expect(validator.check(entity)).rejects.toThrow(/type/); }); + + it('rejects empty type', async () => { + (entity as any).spec.type = ''; + await expect(validator.check(entity)).rejects.toThrow(/type/); + }); });