refactor: apply review suggestion

Signed-off-by: Camila Belo <camilaibs@gmail.com>

.changeset/many-moles-sing.md

@@ -2,4 +2,4 @@
 '@backstage/backend-common': patch
 ---
 
-Deprecate the legacy `createServiceBuilder`.
+We are deprecating the legacy `createServiceBuilder` factory, so if you are still using it, please checkout the migration guide and [migrate](https://backstage.io/docs/backend-system/building-plugins-and-modules/migrating) your plugin to use the new backend system.

docs/backend-system/building-plugins-and-modules/08-migrating.md

@@ -214,3 +214,44 @@ The above module can then be installed by the integrator alongside the kubernete
 backend.add(import('@backstage/plugin-kubernetes-backend'));
 backend.add(import('@internal/gke-cluster-supplier'));
 ```
+
+### Dev Server
+
+Follow the steps below to run your migrated plugin on a local development server:
+
+1. First, delete the `src/run.js` and `src/service/standaloneServer.js` files in case they exist (the `backstage-cli` previously used these files to run legacy backend plugins locally, but they are no longer required).
+
+2. Next, create a new development backend in the `dev/index.js` file. The dev server is a lite version of a backend app that is mainly used to run your plugin locally, so a simple `kubernetes` backend local development server would look like this:
+
+```ts title="in dev/index.js"
+// This package should be installed as a `dev` dependency
+import { createBackend } from '@backstage/backend-defaults';
+
+const backend = createBackend();
+// Path to the file where the plugin is export as default
+backend.add(import('../src'));
+backend.start();
+```
+
+The development server created above will be automatically configured with the default dependency factories, but if you need to mock some of the services your plugin relies on, such as the `rootConfig` service, you can use one of the `mockServices` factories:
+
+```ts title="in dev/index.js"
+//...
+// This package should be installed as `devDependecies`
+import { mockServices } from '@backstage/backend-test-utils';
+
+const backend = createBackend();
+// ...
+backend.add(
+  mockServices.rootConfig.factory({
+    data: {
+      // your config mocked values goes here
+    },
+  }),
+);
+// ...
+```
+
+Checkout the [custom service implementations](https://backstage.io/docs/backend-system/building-backends/index#custom-service-implementations) documentation and also the [core service configurations](https://backstage.io/docs/backend-system/core-services/index) page in case you'd like to create your own custom mock factory for one or more services.
+
+3. Now you can finally start your plugin locally by running `yarn start` from the root folder of your plugin.

packages/backend-common/api-report.md

@@ -599,7 +599,7 @@ export type LegacyRootDatabaseService = {
   forPlugin(pluginId: string): PluginDatabaseManager;
 };
 
-// @public
+// @public @deprecated
 export function loadBackendConfig(options: {
   logger: LoggerService;
   remote?: LoadConfigOptionsRemote;

packages/backend-common/src/config.ts

@@ -29,6 +29,7 @@ import { setRootLoggerRedactionList } from './logging/createRootLogger';
  * This function should only be called once, during the initialization of the backend.
  *
  * @public
+ * @deprecated Use {@link @backstage/backend-app-api#loadBackendConfig} instead.
  */
 export async function loadBackendConfig(options: {
   logger: LoggerService;

packages/backend-common/src/service/createServiceBuilder.ts

@@ -20,7 +20,7 @@ import { ServiceBuilder } from './types';
 /**
  * Creates a new service builder.
  * @public
- * @deprecated We are going to deprecated this old way of creating services in a near future, if you are using this service helper, please checkout the migration guide and make sure you migrate your backend to use the new system: https://backstage.io/docs/backend-system/building-backends/migrating.
+ * @deprecated We are going to deprecated this old way of creating services in a near future, if you are using this service helper, please checkout the {@link https://backstage.io/docs/backend-system/building-backends/migrating | backend} and {@link https://backstage.io/docs/backend-system/building-plugins-and-modules/migrating | plugin} migration guides.
  */
 export function createServiceBuilder(_module: NodeModule): ServiceBuilder {
   return new ServiceBuilderImpl(_module);

plugins/app-backend/dev/index.ts

@@ -15,7 +15,13 @@
  */
 
 import { createBackend } from '@backstage/backend-defaults';
+import { mockServices } from '@backstage/backend-test-utils';
 
 const backend = createBackend();
+backend.add(
+  mockServices.rootConfig.factory({
+    data: { app: { packageName: 'example-app' } },
+  }),
+);
 backend.add(import('../src/alpha'));
 backend.start();

plugins/user-settings-backend/dev/index.ts

@@ -15,35 +15,9 @@
  */
 
 import { createBackend } from '@backstage/backend-defaults';
-import {
-  coreServices,
-  createServiceFactory,
-} from '@backstage/backend-plugin-api';
-import { IdentityApi } from '@backstage/plugin-auth-node';
-
-const identityMock: IdentityApi = {
-  async getIdentity({ request }) {
-    const token = request.headers.authorization?.split(' ')[1];
-    return {
-      identity: {
-        type: 'user',
-        ownershipEntityRefs: [],
-        userEntityRef: token || 'user:default/john_doe',
-      },
-      token: token || 'no-token',
-    };
-  },
-};
+import { mockServices } from '@backstage/backend-test-utils';
 
 const backend = createBackend();
-backend.add(
-  createServiceFactory(() => ({
-    service: coreServices.identity,
-    deps: {},
-    async factory() {
-      return identityMock;
-    },
-  })),
-);
+backend.add(mockServices.identity.factory());
 backend.add(import('../src/alpha'));
 backend.start();