core-compat-api: add notes on way forward with legacy compatibility

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
Co-authored-by: Camila Belo <camilaibs@gmail.com>
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

packages/core-compat-api/src/collectLegacyRoutes.tsx

@@ -30,6 +30,34 @@ import {
 } from '@backstage/core-plugin-api';
 import { convertLegacyRouteRef } from '@backstage/core-plugin-api/alpha';
 
+/*
+
+# Legacy interoperability
+
+Use-cases (prioritized):
+ 1. Slowly migrate over an existing app to DI, piece by piece
+ 2. Use a legacy plugin in a new DI app
+ 3. Use DI in an existing legacy app
+
+Starting point: use-case #1
+
+Potential solutions:
+ 1. Codemods (we're not considering this for now)
+ 2. Legacy apps are migrated bottom-up, i.e. keep legacy root, replace pages with DI
+ 3. Legacy apps are migrated top-down i.e. switch out base to DI, legacy adapter allows for usage of existing app structure
+
+Chosen path: #3
+
+Existing tasks:
+  - Adopters can migrate their existing app gradually (~4)
+    - Example-app uses legacy base with DI adapters
+    - Create an API that lets you inject DI into existing apps - working assumption is that this is enough
+  - Adopters can use legacy plugins in DI through adapters (~8)
+    - App-next uses DI base with legacy adapters
+    - Create a legacy adapter that is able to take an existing extension tree
+
+*/
+
 export function collectLegacyRoutes(
   flatRoutesElement: JSX.Element,
 ): BackstagePlugin[] {