Merge branch 'backstage:master' into feat/techdocs-azurite-support

docs/accessibility/index.md

@@ -15,35 +15,35 @@ There are multiple ways to contribute to making Backstage more accessible, you'l
 If your plugin lives in the [Backstage main repository](https://github.com/backstage/backstage/) you can modify the [urls in the Lighthouse config](https://github.com/backstage/backstage/blob/39ba2284d73885b7ca8290cb38e2b1e4d983c8d6/lighthouserc.js#L19-L34) to run the Lighthouse checks on urls where your plugin exists as well. E.g.
 
 ```diff
- ci: {
-    collect: {
-      url: [
+  ci: {
+     collect: {
+       url: [
+         /** Software Catalog */
+         'http://localhost:3000/catalog',
+         'http://localhost:3000/catalog-import',
+         'http://localhost:3000/catalog/default/component/backstage',
+         ...
 +        /** Your plugin paths */
 +        'http://localhost:3000/your-plugin-path,
-        /** Software Catalog */
-        'http://localhost:3000/catalog',
-        'http://localhost:3000/catalog-import',
-        'http://localhost:3000/catalog/default/component/backstage',
+       ],
+       settings: {
         ...
-      ],
-      settings: {
-       ...
-      },
-     ...
-    },
-    assert: {
+       },
       ...
-    },
-  },
+     },
+     assert: {
+       ...
+     },
+   },
 ```
 
-To make sure the [Accessibility Github workflow](https://github.com/backstage/backstage/blob/master/.github/workflows/verify_accessibility.yml) is running when changes are made to your plugin folders, modify the [list of paths](https://github.com/backstage/backstage/blob/10759b6ad2561bd86183ad940256f9a309c7a6b0/.github/workflows/verify_accessibility.yml#L7-L16).
+To make sure the [Accessibility GitHub workflow](https://github.com/backstage/backstage/blob/master/.github/workflows/verify_accessibility.yml) is running when changes are made to your plugin folders, modify the [list of paths](https://github.com/backstage/backstage/blob/10759b6ad2561bd86183ad940256f9a309c7a6b0/.github/workflows/verify_accessibility.yml#L7-L16).
 
 ### Run the Lighthouse CLI locally when developing new features
 
 If you want to use the Lighthouse CLI and run the checks based on the config you can use the following command:
 
-```
+```shell
 yarn dlx @lhci/cli@0.11.x autorun
 ```
 

docs/backend-system/building-plugins-and-modules/01-index.md

@@ -85,6 +85,8 @@ declare a dependency on the plugin package itself. This is to avoid a direct
 dependency and potentially cause duplicate installations of the plugin package,
 while duplicate installations of library packages should always be supported.
 
+To create a Backend module, run `yarn new`, select `backend-module`, and fill out the rest of the prompts. This will create a new package at `plugins/<pluginId>-backend-module-<moduleId>`.
+
 The following is an example of how to create a module that adds a new processor
 using the `catalogProcessingExtensionPoint`:
 

docs/backend-system/building-plugins-and-modules/02-testing.md

@@ -118,7 +118,7 @@ describe('MyDatabaseClass', () => {
   // "physical" databases to test against is much costlier than creating the
   // "logical" databases within them that the individual tests use.
   const databases = TestDatabases.create({
-    ids: ['POSTGRES_13', 'POSTGRES_9', 'SQLITE_3'],
+    ids: ['POSTGRES_13', 'POSTGRES_9', 'SQLITE_3', 'MYSQL_8'],
   });
 
   // Just an example of how to conveniently bundle up the setup code

docs/features/software-catalog/references.md

@@ -23,9 +23,9 @@ compound reference structure.
 
 ## String References
 
-This is the most common alternative, that is used in almost all circumstances.
+This is the most common alternative and is used in almost all circumstances.
 
-The string is on the form `[<kind>:][<namespace>/]<name>`, that is, it is
+The string is of the form `[<kind>:][<namespace>/]<name>`. That is, it is
 composed of between one and three parts in this specific order, without any
 additional encoding:
 

docs/integrations/azure/locations.md

@@ -19,10 +19,10 @@ Using a service principal:
 integrations:
   azure:
     - host: dev.azure.com
-      credential:
-        clientId: ${CLIENT_ID}
-        clientSecret: ${CLIENT_SECRET}
-        tenantId: ${TENANT_ID}
+      credentials:
+        - clientId: ${AZURE_CLIENT_ID}
+          clientSecret: ${AZURE_CLIENT_SECRET}
+          tenantId: ${AZURE_TENANT_ID}
 ```
 
 Using a managed identity:
@@ -31,8 +31,8 @@ Using a managed identity:
 integrations:
   azure:
     - host: dev.azure.com
-      credential:
-        clientId: ${CLIENT_ID}
+      credentials:
+        - clientId: ${AZURE_CLIENT_ID}
 ```
 
 Using a personal access token (PAT):
@@ -41,24 +41,54 @@ Using a personal access token (PAT):
 integrations:
   azure:
     - host: dev.azure.com
-      token: ${AZURE_TOKEN}
+      credentials:
+        - personalAccessToken: ${PERSONAL_ACCESS_TOKEN}
 ```
 
+You can use specific credentials for different Azure DevOps organizations by specifying the `organizations` field on the credential:
+
+```yaml
+integrations:
+  azure:
+    - host: dev.azure.com
+      credentials:
+        - organizations:
+            - my-org
+            - my-other-org
+          clientId: ${AZURE_CLIENT_ID}
+          clientSecret: ${AZURE_CLIENT_SECRET}
+          tenantId: ${AZURE_TENANT_ID}
+        - organizations:
+            - another-org
+          clientId: ${AZURE_CLIENT_ID}
+        - organizations:
+            - yet-another-org
+          personalAccessToken: ${PERSONAL_ACCESS_TOKEN}
+```
+
+If you do not specify the `organizations` field the credential will be used for all organizations for which no other credential is configured.
+
 > Note: An Azure DevOps provider is added automatically at startup for
 > convenience, so you only need to list it if you want to supply a
-> [token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate),
+> [personalAccessToken](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate),
 > a [service principal](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity),
 > or a [managed identity](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity)
 
 The configuration is a structure with these elements:
 
-- `host`: The DevOps host; only `dev.azure.com` is supported.
-- `token` (optional): A personal access token as expected by Azure DevOps.
-- `credential`: (optional): A service principal or managed identity
+- `credentials`: (optional): A service principal, managed identity, or personal access token
+
+The `credentials` element is a structure with these elements:
+
+- `organizations`: (optional): A list of organizations for which this credential should be used. If not specified the credential will be used for all organizations for which no other credential is configured.
+- `clientId`: The client ID of the service principal or managed identity (required for service principal and managed identities)
+- `clientSecret`: The client secret of the service principal (required for service principal)
+- `tenantId`: The tenant ID of the service principal (required for service principal)
+- `personalAccessToken`: The personal access token (required for personal access token)
 
 > Note:
 >
-> - `token` and `credential` are mutually exclusive.
 > - You cannot use a service principal or managed identity for Azure DevOps Server (on-premises) organizations
 > - You can only use a service principal or managed identity for Azure AD backed Azure DevOps organizations
-> - The token should just be provided as the raw token generated by Azure DevOps using the format `raw_token` with no base64 encoding. Formatting and base64'ing is handled by dependent libraries handling the Azure DevOps API
+> - You can only specify one credential per host without any organizations specified
+> - The personal access token should just be provided as the raw token generated by Azure DevOps using the format `raw_token` with no base64 encoding. Formatting and base64'ing is handled by dependent libraries handling the Azure DevOps API

docs/plugins/integrating-plugin-into-software-catalog.md

@@ -37,7 +37,7 @@ You can access the currently selected entity using the backstage api
 import { useEntity } from '@backstage/plugin-catalog-react';
 
 export const MyPluginEntityContent = () => {
-  const { entity, loading, error, refresh } = useEntity();
+  const entity = useEntity();
 
   // Do something with the entity data...
 };

docs/publishing.md

@@ -18,6 +18,22 @@ PR is merged. This is typically done every Tuesday around noon CET.
 **This emergency release process is intended only for the Backstage
 maintainers.**
 
+Given one or more PRs towards master that we want to create a patch release for, run the following script from the repo root:
+
+```bash
+./scripts/patch-release-for-pr.js <pr-number> <pr-number-2> ...
+```
+
+Wait until the script has finished executing, at the end of the output you will find a link of the format `https://github.com/backstage/backstage/compare/patch/...`. Open this link in your browser to create a PR for the patch release. Finish the sentence "This release fixes an issue where..." and create the PR.
+
+Once the PR has been approved and merged, the patch release will be automatically created. The patch release is complete when a notification has been posted to Discord in the `#announcements` channel. Keep an eye on "Deploy Packages" workflow and re-trigger if it fails. It is safe to re-trigger any part of this workflow, including the release step.
+
+If the above process fails, you can fall back to the manual process documented below.
+
+### Old Process
+
+This is the old and manual process that we used before the patch script, provided here as a reference:
+
 For this example we will be using the `@backstage/plugin-foo` package as an
 example and assume that it is currently version `6.5.0` in the master branch.