backend-plugin-api: update module ID format

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/rare-hotels-cough.md

@@ -0,0 +1,5 @@
+---
+'@backstage/backend-plugin-api': patch
+---
+
+Added documentation for `createBackendModule`, with guidelines for choosing a module ID.

.changeset/young-bugs-remember.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-catalog-backend-module-github': patch
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Updated the `moduleId` of the experimental module export.

packages/backend-plugin-api/api-report.md

@@ -71,7 +71,7 @@ export const cacheServiceRef: ServiceRef<PluginCacheManager, 'plugin'>;
 // @public (undocumented)
 export const configServiceRef: ServiceRef<Config, 'root'>;
 
-// @public (undocumented)
+// @public
 export function createBackendModule<
   TOptions extends object | undefined = undefined,
 >(

packages/backend-plugin-api/src/wiring/factories.ts

@@ -69,7 +69,18 @@ export interface BackendModuleConfig<TOptions> {
   ): void;
 }
 
-/** @public */
+/**
+ * @public
+ *
+ * Creates a new backend module for a given plugin.
+ *
+ * The `moduleId` should be equal to the module-specific prefix of the exported name, such
+ * that the full name is `moduleId + PluginId + "Module"`. For example, a GitHub entity
+ * provider module for the `catalog` plugin might have the module ID `'githubEntityProvider'`,
+ * and the full exported name would be `githubEntityProviderCatalogModule`.
+ *
+ * The `pluginId` should exactly match the `id` of the plugin that the module extends.
+ */
 export function createBackendModule<
   TOptions extends object | undefined = undefined,
 >(

plugins/catalog-backend-module-github/src/module.ts

@@ -41,7 +41,7 @@ export type GithubEntityProviderCatalogModuleOptions = {
  */
 export const githubEntityProviderCatalogModule = createBackendModule({
   pluginId: 'catalog',
-  moduleId: 'github-entity-provider',
+  moduleId: 'githubEntityProvider',
   register(env, options?: GithubEntityProviderCatalogModuleOptions) {
     env.registerInit({
       deps: {

plugins/catalog-node/src/catalogService.test.ts

@@ -37,7 +37,7 @@ describe('catalogServiceRef', () => {
     });
 
     const testModule = createBackendModule({
-      moduleId: 'test.module',
+      moduleId: 'test',
       pluginId: 'test',
       register(env) {
         env.registerInit({

plugins/scaffolder-backend/src/extension/ScaffolderCatalogModule.ts

@@ -22,7 +22,7 @@ import { ScaffolderEntitiesProcessor } from '../processor';
  * Registers the ScaffolderEntitiesProcessor with the catalog processing extension point.
  */
 export const scaffolderCatalogModule = createBackendModule({
-  moduleId: 'scaffolder.module',
+  moduleId: 'scaffolder',
   pluginId: 'catalog',
   register(env) {
     env.registerInit({