catalog: mark ancestors and descendants for deprecation (#3392)

.changeset/forty-buses-watch.md

@@ -0,0 +1,14 @@
+---
+'@backstage/catalog-model': patch
+'@backstage/plugin-catalog-backend': patch
+---
+
+Marked the `Group` entity fields `ancestors` and `descendants` for deprecation on Dec 6th, 2020. See https://github.com/backstage/backstage/issues/3049 for details.
+
+Code that consumes these fields should remove those usages as soon as possible. There is no current or planned replacement for these fields.
+
+The BuiltinKindsEntityProcessor has been updated to inject these fields as empty arrays if they are missing. Therefore, if you are on a catalog instance that uses the updated version of this code, you can start removing the fields from your source catalog-info.yaml data as well, without breaking validation.
+
+After Dec 6th, the fields will be removed from types and classes of the Backstage repository. At the first release after that, they will not be present in released packages either.
+
+If your catalog-info.yaml files still contain these fields after the deletion, they will still be valid and your ingestion will not break, but they won't be visible in the types for consuming code.

docs/features/software-catalog/descriptor-format.md

@@ -700,6 +700,11 @@ sufficient to enter only the `metadata.name` field of that group.
 
 ### `spec.ancestors` [required]
 
+**NOTE**: This field was marked for deprecation on Nov 22nd, 2020. It will be
+removed entirely from the model on Dec 6th, 2020 in the repository and will not
+be present in released packages following the next release after that. Please
+update your code to not consume this field before the removal date.
+
 The recursive list of parents up the hierarchy, by stepping through parents one
 by one. The list must be present, but may be empty if `parent` is not present.
 The first entry in the list is equal to `parent`, and then the following ones
@@ -728,6 +733,11 @@ sufficient to enter only the `metadata.name` field of those groups.
 
 ### `spec.descendants` [required]
 
+**NOTE**: This field was marked for deprecation on Nov 22nd, 2020. It will be
+removed entirely from the model on Dec 6th, 2020 in the repository and will not
+be present in released packages following the next release after that. Please
+update your code to not consume this field before the removal date.
+
 The immediate and recursive child groups of this group in the hierarchy
 (children, and children's children, etc.). The list must be present, but may be
 empty if there are no child groups. The items are not guaranteed to be ordered

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

@@ -57,8 +57,22 @@ export interface GroupEntityV1alpha1 extends Entity {
   spec: {
     type: string;
     parent?: string;
+    /**
+     * @deprecated This field will disappear on Dec 6th, 2020. Please remove
+     *             any consuming code. Producers can stop producing this field
+     *             before that date, as long as the catalog backend uses the
+     *             BuiltinKindsEntityProcessor which inserts the fields in the
+     *             mean time.
+     */
     ancestors: string[];
     children: string[];
+    /**
+     * @deprecated This field will disappear on Dec 6th, 2020. Please remove
+     *             any consuming code. Producers can stop producing this field
+     *             before that date, as long as the catalog backend uses the
+     *             BuiltinKindsEntityProcessor which inserts the fields in the
+     *             mean time.
+     */
     descendants: string[];
   };
 }

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

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * 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 { BuiltinKindsEntityProcessor } from './BuiltinKindsEntityProcessor';
+
+describe('BuiltinKindsEntityProcessor', () => {
+  it('fills in fields for #3049', async () => {
+    const p = new BuiltinKindsEntityProcessor();
+    const result = await p.preProcessEntity({
+      apiVersion: 'backstage.io/v1alpha1',
+      kind: 'Group',
+      metadata: {
+        name: 'n',
+      },
+      spec: {
+        type: 't',
+        children: [],
+      } as any,
+    });
+    expect(result).toEqual({
+      apiVersion: 'backstage.io/v1alpha1',
+      kind: 'Group',
+      metadata: {
+        name: 'n',
+      },
+      spec: {
+        type: 't',
+        children: [],
+        ancestors: [],
+        descendants: [],
+      },
+    });
+  });
+});

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

@@ -35,6 +35,25 @@ export class BuiltinKindsEntityProcessor implements CatalogProcessor {
     userEntityV1alpha1Validator,
   ];
 
+  async preProcessEntity(entity: Entity): Promise<Entity> {
+    // NOTE(freben): Part of Group field deprecation on Nov 22nd, 2020. Fields
+    // scheduled for removal Dec 6th, 2020. This code can be deleted after that
+    // point. See https://github.com/backstage/backstage/issues/3049
+    if (
+      entity.apiVersion === 'backstage.io/v1alpha1' &&
+      entity.kind === 'Group' &&
+      entity.spec
+    ) {
+      if (!entity.spec.ancestors) {
+        entity.spec.ancestors = [];
+      }
+      if (!entity.spec.descendants) {
+        entity.spec.descendants = [];
+      }
+    }
+    return entity;
+  }
+
   async validateEntityKind(entity: Entity): Promise<boolean> {
     for (const validator of this.validators) {
       const result = await validator.check(entity);