From 1cd1c5cbb0e0be4523560bd2a31e164b52dfcf53 Mon Sep 17 00:00:00 2001
From: Enrico Alvarenga <enrico.alvarenga@segment.com>
Date: Mon, 19 Dec 2022 12:53:38 -0800
Subject: [PATCH] docs: update docs referencing OwnerPicker and EntityPicker

Signed-off-by: Enrico Alvarenga <enrico.alvarenga@segment.com>
---
 .changeset/selfish-phones-smoke.md            | 30 ++++++++++++++++++-
 .../software-templates/writing-templates.md   | 10 +++----
 .../README.md                                 |  8 ++---
 .../scaffolder-backend-module-rails/README.md |  8 ++---
 .../README.md                                 |  8 ++---
 5 files changed, 46 insertions(+), 18 deletions(-)

diff --git a/.changeset/selfish-phones-smoke.md b/.changeset/selfish-phones-smoke.md
index a9583cff94..bb6f7f7211 100644
--- a/.changeset/selfish-phones-smoke.md
+++ b/.changeset/selfish-phones-smoke.md
@@ -2,4 +2,32 @@
 '@backstage/plugin-scaffolder': patch
 ---
 
-Added a new prop to OwnerPicker and EntityPicker components to support filtering options by any field(s) of an entity.
+Added the catalogFilter prop to OwnerPicker and EntityPicker components to support filtering options by any field(s) of an entity.
+
+The `allowedKinds` field has been deprecated. Use `catalogFilter` instead. This field allows users to specify a filter on the shape of [EntityFilterQuery](https://github.com/backstage/backstage/blob/774c42003782121d3d6b2aa5f2865d53370c160e/packages/catalog-client/src/types/api.ts#L74), which can be passed into the CatalogClient. See examples below:
+
+- Get all entities of kind `Group`
+
+  ```yaml
+  owner:
+    title: Owner
+    type: string
+    description: Owner of the component
+    ui:field: OwnerPicker
+    ui:options:
+      catalogFilter:
+        - kind: Group
+  ```
+
+- Get entities of kind `Group` and spec.type `team`
+  ```yaml
+  owner:
+    title: Owner
+    type: string
+    description: Owner of the component
+    ui:field: OwnerPicker
+    ui:options:
+      catalogFilter:
+        - kind: Group
+          spec.type: team
+  ```
diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md
index 826121bd02..d86ec33e7a 100644
--- a/docs/features/software-templates/writing-templates.md
+++ b/docs/features/software-templates/writing-templates.md
@@ -44,8 +44,8 @@ spec:
           description: Owner of the component
           ui:field: OwnerPicker
           ui:options:
-            allowedKinds:
-              - Group
+            catalogFilter:
+              kind: Group
     - title: Choose a location
       required:
         - repoUrl
@@ -459,7 +459,7 @@ an owner for them. Ideally, users should be able to select an owner when they go
 through the scaffolder form from the users and groups already known to
 Backstage. The `OwnerPicker` is a custom field that generates a searchable list
 of groups and/or users already in the catalog to pick an owner from. You can
-specify which of the two kinds are listed in the `allowedKinds` option:
+specify which of the two kinds (or both) are listed in the `catalogFilter.kind` option:
 
 ```yaml
 owner:
@@ -468,8 +468,8 @@ owner:
   description: Owner of the component
   ui:field: OwnerPicker
   ui:options:
-    allowedKinds:
-      - Group
+    catalogFilter:
+      kind: [Group, User]
 ```
 
 ## `spec.steps` - `Action[]`
diff --git a/plugins/scaffolder-backend-module-cookiecutter/README.md b/plugins/scaffolder-backend-module-cookiecutter/README.md
index 642ef25edf..c96136a0f9 100644
--- a/plugins/scaffolder-backend-module-cookiecutter/README.md
+++ b/plugins/scaffolder-backend-module-cookiecutter/README.md
@@ -73,16 +73,16 @@ spec:
           description: Owner of the component
           ui:field: OwnerPicker
           ui:options:
-            allowedKinds:
-              - Group
+            catalogFilter:
+              kind: Group
         system:
           title: System
           type: string
           description: System of the component
           ui:field: EntityPicker
           ui:options:
-            allowedKinds:
-              - System
+            catalogFilter:
+              kind: System
             defaultKind: System
 
     - title: Choose a location
diff --git a/plugins/scaffolder-backend-module-rails/README.md b/plugins/scaffolder-backend-module-rails/README.md
index 9d1316473d..066aa0cedc 100644
--- a/plugins/scaffolder-backend-module-rails/README.md
+++ b/plugins/scaffolder-backend-module-rails/README.md
@@ -74,16 +74,16 @@ spec:
           description: Owner of the component
           ui:field: OwnerPicker
           ui:options:
-            allowedKinds:
-              - Group
+            catalogFilter:
+              kind: Group
         system:
           title: System
           type: string
           description: System of the component
           ui:field: EntityPicker
           ui:options:
-            allowedKinds:
-              - System
+            catalogFilter:
+              kind: System
             defaultKind: System
 
     - title: Choose a location
diff --git a/plugins/scaffolder-backend-module-yeoman/README.md b/plugins/scaffolder-backend-module-yeoman/README.md
index 8ad3a74fe2..aee83ebe0a 100644
--- a/plugins/scaffolder-backend-module-yeoman/README.md
+++ b/plugins/scaffolder-backend-module-yeoman/README.md
@@ -73,16 +73,16 @@ spec:
           description: Owner of the component
           ui:field: OwnerPicker
           ui:options:
-            allowedKinds:
-              - Group
+            catalogFilter:
+              kind: Group
         system:
           title: System
           type: string
           description: System of the component
           ui:field: EntityPicker
           ui:options:
-            allowedKinds:
-              - System
+            catalogFilter:
+              kind: System
             defaultKind: System
 
     - title: Choose a location