From 3d870192697b7481ceb063152fa2fe40bd110347 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Fri, 14 Jan 2022 14:14:20 +0100
Subject: [PATCH] catalog-react: route ref deprecations + deduplication and
 docs

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 .changeset/hungry-buttons-fetch.md  |  9 ++++++++
 plugins/catalog-react/api-report.md |  8 +++----
 plugins/catalog-react/src/routes.ts | 33 ++++++++++++++++++++++++-----
 3 files changed, 41 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/hungry-buttons-fetch.md

diff --git a/.changeset/hungry-buttons-fetch.md b/.changeset/hungry-buttons-fetch.md
new file mode 100644
index 0000000000..f2f9bc26bc
--- /dev/null
+++ b/.changeset/hungry-buttons-fetch.md
@@ -0,0 +1,9 @@
+---
+'@backstage/plugin-catalog-react': patch
+---
+
+The `entityRouteRef` is now a well-known route that should be imported directly from `@backstage/plugin-catalog-react`. It is guaranteed to be globally unique across duplicate installations of the `@backstage/plugin-catalog-react`, starting at this version.
+
+Deprecated `entityRoute` in favor of `entityRouteRef`.
+
+Deprecated `rootRoute` and `catalogRouteRef`. If you want to refer to the catalog index page from a public plugin you now need to use an `ExternalRouteRef` instead. For private plugins it is possible to take the shortcut of referring directly to `catalogPlugin.routes.indexPage` instead.
diff --git a/plugins/catalog-react/api-report.md b/plugins/catalog-react/api-report.md
index 90fa193bfd..a9395c180e 100644
--- a/plugins/catalog-react/api-report.md
+++ b/plugins/catalog-react/api-report.md
@@ -101,7 +101,7 @@ export type CatalogReactUserListPickerClassKey =
 
 // Warning: (ae-missing-release-tag) "catalogRouteRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export const catalogRouteRef: RouteRef<undefined>;
 
 // Warning: (ae-missing-release-tag) "createDomainColumn" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -591,7 +591,7 @@ export const EntityRefLinks: ({
 
 // Warning: (ae-missing-release-tag) "entityRoute" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export const entityRoute: RouteRef<{
   name: string;
   kind: string;
@@ -609,7 +609,7 @@ export function entityRouteParams(entity: Entity): {
 
 // Warning: (ae-missing-release-tag) "entityRouteRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export const entityRouteRef: RouteRef<{
   name: string;
   kind: string;
@@ -812,7 +812,7 @@ export function reduceEntityFilters(
 
 // Warning: (ae-missing-release-tag) "rootRoute" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export const rootRoute: RouteRef<undefined>;
 
 // @public
diff --git a/plugins/catalog-react/src/routes.ts b/plugins/catalog-react/src/routes.ts
index f29d52f08a..1fcbd14866 100644
--- a/plugins/catalog-react/src/routes.ts
+++ b/plugins/catalog-react/src/routes.ts
@@ -16,20 +16,43 @@
 
 import { Entity, ENTITY_DEFAULT_NAMESPACE } from '@backstage/catalog-model';
 import { createRouteRef } from '@backstage/core-plugin-api';
+import { getOrCreateGlobalSingleton } from '@backstage/version-bridge';
 
 // TODO(Rugvip): Move these route refs back to the catalog plugin once we're all ported to using external routes
+/**
+ * @deprecated Use an `ExternalRouteRef` instead, which can point to `catalogPlugin.routes.catalogIndex`.
+ */
 export const rootRoute = createRouteRef({
   id: 'catalog',
 });
 
+/**
+ * @deprecated Use an `ExternalRouteRef` instead, which can point to `catalogPlugin.routes.catalogIndex`.
+ */
 export const catalogRouteRef = rootRoute;
 
-export const entityRoute = createRouteRef({
-  id: 'catalog:entity',
-  params: ['namespace', 'kind', 'name'],
-});
+/**
+ * A stable route ref that points to the catalog page for an individual entity.
+ *
+ * This `RouteRef` can be imported and used directly, and does not need to be referenced
+ * via an `ExternalRouteRef`.
+ *
+ * If you want to replace the `EntityPage` from `@backstage/catalog-plugin` in your app,
+ * you need to use the `entityRouteRef` as the mount point instead of your own.
+ */
+export const entityRouteRef = getOrCreateGlobalSingleton(
+  'catalog:entity-route-ref',
+  () =>
+    createRouteRef({
+      id: 'catalog:entity',
+      params: ['namespace', 'kind', 'name'],
+    }),
+);
 
-export const entityRouteRef = entityRoute;
+/**
+ * @deprecated use `entityRouteRef` instead.
+ */
+export const entityRoute = entityRouteRef;
 
 // Utility function to get suitable route params for entityRoute, given an
 // entity instance