Merge branch 'master' into feat-root-logger-service-overrides

docs/backend-system/core-services/actions-registry.md

@@ -45,7 +45,7 @@ When an action is executed, it receives a context object (`ActionsRegistryAction
 Here's an example of how to register an action with the Actions Registry Service:
 
 ```typescript
-import { ActionsRegistryService } from '@backstage/backend-plugin-api';
+import { ActionsRegistryService } from '@backstage/backend-plugin-api/alpha';
 
 export function registerMyActions(actionsRegistry: ActionsRegistryService) {
   // Register a simple read-only action

docs/features/software-catalog/descriptor-format.md

@@ -239,18 +239,33 @@ Example: `visits-tracking-service`, `CircleciBuildsDumpV2_avro_gcs`
 ### `namespace` [optional]
 
 The ID of a namespace that the entity belongs to. This field is optional, and
-currently has no special semantics apart from bounding the name uniqueness
-constraint if specified. It is reserved for future use and may get broader
-semantic implication later.
+has no special semantics apart from bounding the name uniqueness constraint if
+specified.
 
-For now, it is recommended to not specify a namespace unless you have specific
-need to do so. This means the entity belongs to the `"default"` namespace.
+This can be used for ingesting entities (of the same kind) from different
+contexts where their names might otherwise end up overlapping. An example of
+this is to import users and groups from your HR system into the default
+namespace, but also wanting to ingest users from your GitHub enterprise
+installation and those potentially having the same names as the HR system users.
+Then you could set up your GitHub enterprise ingestion to place those users in a
+`"ghe"` namespace to avoid collisions.
+
+If you do not specify a namespace, it assumes the value `"default"`.
 
 Namespaces must be sequences of `[a-zA-Z0-9]`, possibly separated by `-`, at
-most 63 characters in total. Namespace names are case insensitive and will be rendered as lower case in most places.
+most 63 characters in total. Namespace names are case insensitive and will be
+rendered as lower case in most places.
 
 Example: `tracking-services`, `payment`
 
+Note that using namespaces typically means that you need to explicitly specify
+the namespace when referring to the entity. In some contexts, notably in entity
+catalog-info definition YAML files, you often refer to other entities by name.
+When they are in a different namespace, you need to use the syntax
+`<namespace>/<name>`, while if they are in the default namespace you can omit
+that part as a shorthand. Therefore it's practical to use the default namespace
+for simplicity until it's necessary to use supplemental ones. See [the references article](references.md) for more information.
+
 ### `uid` [output]
 
 Each entity gets an automatically generated globally unique ID when it first

docs/frontend-system/building-apps/08-migrating.md

@@ -913,7 +913,7 @@ const app = createApp({
 If you are not using the default `<CatalogIndexPage />` you can install your custom catalog page as an override for now instead, and fully migrate it to the new system later.
 
 ```tsx title="in packages/app/src/App.tsx"
-/* highlight-remove-start */
+/* highlight-add-start */
 const catalogPluginOverride = catalogPlugin.withOverrides({
   extensions: [
     catalogPlugin.getExtension('page:catalog').override({
@@ -928,13 +928,13 @@ const catalogPluginOverride = catalogPlugin.withOverrides({
     }),
   ],
 });
-/* highlight-remove-end */
+/* highlight-add-end */
 
 const app = createApp({
-  /* highlight-remove-next-line */
-  features: [catalogPlugin, convertedOptionsModule, ...convertedRootFeatures],
-  /* highlight-add-next-line */
   features: [
+    /* highlight-remove-next-line */
+    catalogPlugin,
+    /* highlight-add-next-line */
     catalogPluginOverride,
     convertedOptionsModule,
     ...convertedRootFeatures,

docs/frontend-system/building-plugins/01-index.md

@@ -185,7 +185,7 @@ export const examplePlugin = createFrontendPlugin({
 
 ## Plugin specific extensions
 
-There are many different plugins that you can extend with additional functionality through extensions. One such plugin is [the catalog plugin](../../features/software-catalog/), one of the core features of Backstage. It lets you catalog the software in your organization, where each item in the catalog has its own page that can be populated with tools and information relating to that catalog entity. In this example we will explore how our plugin can provide such a tool to display on an entity page.
+There are many different plugins that you can extend with additional functionality through extensions. One such plugin is [the catalog plugin](https://backstage.io/docs/features/software-catalog/), one of the core features of Backstage. It lets you catalog the software in your organization, where each item in the catalog has its own page that can be populated with tools and information relating to that catalog entity. In this example we will explore how our plugin can provide such a tool to display on an entity page.
 
 ```tsx title="in src/plugin.ts - An example entity content extension"
 import { EntityContentBlueprint } from '@backstage/plugin-catalog-react/alpha';

docs/integrations/github/discovery.md

@@ -2,7 +2,7 @@
 id: discovery
 title: GitHub Discovery
 sidebar_label: Discovery
-description: Automatically discovering catalog entities from repositories in a GitHub organization
+description: Automatically discovering catalog entities from repositories in a GitHub organization or App
 ---
 
 :::info
@@ -12,8 +12,8 @@ This documentation is written for [the new backend system](../../backend-system/
 ## GitHub Provider
 
 The GitHub integration has a discovery provider for discovering catalog
-entities within a GitHub organization. The provider will crawl the GitHub
-organization and register entities matching the configured path. This can be
+entities within a GitHub organization or App. The provider will crawl the GitHub
+organization or App and register entities matching the configured path. This can be
 useful as an alternative to static locations or manually adding things to the
 catalog. This is the preferred method for ingesting entities into the catalog.
 
@@ -252,7 +252,7 @@ catalog:
         catalogPath: '/catalog-info.yaml' # string
 ```
 
-This provider supports multiple organizations via unique provider IDs.
+This provider supports multiple organizations and apps via unique provider IDs.
 
 :::note Note
 
@@ -288,9 +288,11 @@ If you do so, `default` will be used as provider ID.
     Whether to include archived repositories. Defaults to `false`.
 - **`host`** _(optional)_:
   The hostname of your GitHub Enterprise instance. It must match a host defined in [integrations.github](locations.md).
-- **`organization`**:
+- **`organization`** _(required, unless `app` is set)_:
   Name of your organization account/workspace.
-  If you want to add multiple organizations, you need to add one provider config each.
+  If you want to add multiple organizations, you need to add one provider config each or specify `app` instead.
+- **`app`** _(required, unless `organization` is set)_:
+  ID of your GitHub App.
 - **`validateLocationsExist`** _(optional)_:
   Whether to validate locations that exist before emitting them.
   This option avoids generating locations for catalog info files that do not exist in the source repository.