Merge branch 'master' of https://github.com/backstage/backstage into feat/reference-external-docs

This commit is contained in:
jrwpatterson
2023-08-23 08:33:33 +10:00
1241 changed files with 43195 additions and 8974 deletions
+18 -18
View File
@@ -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
```
@@ -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`:
@@ -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
@@ -978,9 +978,9 @@ way.
The entries of this array are
[entity references](https://backstage.io/docs/features/software-catalog/references).
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
| [`Group`](#kind-group) (default) | Same as this entity, typically `default` | [`hasMember`, and reverse `memberOf`](well-known-relations.md#memberof-and-hasmember) |
| [`kind`](#apiversion-and-kind-required) | Default [`namespace`](#namespace-optional) | Generated [relation](well-known-relations.md) type |
| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- |
| [`Group`](#kind-group) (default) | Same as this entity, typically `default` | [`parentOf`, and reverse `childOf`](well-known-relations.md#parentof-and-childof) |
### `spec.members` [optional]
+2 -2
View File
@@ -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:
@@ -210,5 +210,6 @@ scaffolder backend:
| JSON Merge Actions | [plugin-scaffolder-json-merge-actions](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-json-merge-actions) | [Drew Hill](https://github.com/arhill05) |
| NPM Actions | [plugin-scaffolder-npm-actions](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-npm-actions) | [Drew Hill](https://github.com/arhill05) |
| Slack Actions | [plugin-scaffolder-backend-module-slack](https://www.npmjs.com/package/@mdude2314/backstage-plugin-scaffolder-backend-module-slack) | [Drew Hill](https://github.com/arhill05) |
| Microsoft Teams Actions | [plugin-scaffolder-backend-module-ms-teams](https://www.npmjs.com/package/@grvpandey11/backstage-plugin-scaffolder-backend-module-ms-teams) | [Gaurav Pandey](https://github.com/grvpandey11) |
Have fun! 🚀
@@ -89,10 +89,8 @@ export const validateKebabCaseValidation = (
then please use `scaffolderPlugin.provide` from there instead and export it part of your `plugin.ts` rather than re-using the `scaffolder.plugin`.
*/
import {
scaffolderPlugin,
createScaffolderFieldExtension,
} from '@backstage/plugin-scaffolder';
import { scaffolderPlugin } from '@backstage/plugin-scaffolder';
import { createScaffolderFieldExtension } from '@backstage/plugin-scaffolder-react';
import {
ValidateKebabCase,
validateKebabCaseValidation,
@@ -133,7 +131,7 @@ Should look something like this instead:
```tsx
import { ValidateKebabCaseFieldExtension } from './scaffolder/ValidateKebabCase';
import { ScaffolderFieldExtensions } from '@backstage/plugin-scaffolder';
import { ScaffolderFieldExtensions } from '@backstage/plugin-scaffolder-react';
const routes = (
<FlatRoutes>
@@ -4,7 +4,7 @@ title: Writing custom step layouts
description: How to override the default step form layout
---
Every form in each step rendered in the frontend uses the default form layout from [react-json-schema-form](https://react-jsonschema-form.readthedocs.io/). It is possible to override this behaviour by supplying a `ui:ObjectFieldTemplate` property for a particular step:
Every form in each step rendered in the frontend uses the default form layout from [react-jsonschema-form](https://rjsf-team.github.io/react-jsonschema-form/docs/). It is possible to override this behaviour by supplying a `ui:ObjectFieldTemplate` property for a particular step:
```yaml
parameters:
@@ -12,7 +12,7 @@ parameters:
ui:ObjectFieldTemplate: TwoColumn
```
This is the same [field](https://react-jsonschema-form.readthedocs.io/en/latest/advanced-customization/custom-templates/#objectfieldtemplate) used by [react-json-schema-form](https://react-jsonschema-form.readthedocs.io/) but we need to add a couple of steps to ensure that the string value of `TwoColumn` above is resolved to a react component.
This is the same [field](https://rjsf-team.github.io/react-jsonschema-form/docs/advanced-customization/custom-templates#objectfieldtemplate) used by [react-jsonschema-form](https://rjsf-team.github.io/react-jsonschema-form/docs/) but we need to add a couple of steps to ensure that the string value of `TwoColumn` above is resolved to a react component.
## Registering a React component as a custom step layout
@@ -499,6 +499,7 @@ template. These follow the same standard format:
- id: fetch-base # A unique id for the step
name: Fetch Base # A title displayed in the frontend
if: ${{ parameters.name }} # Optional condition, skip the step if not truthy
each: ${{ parameters.iterable }} # Optional iterable, run the same step multiple times
action: fetch:template # An action to call
input: # Input that is passed as arguments to the action handler
url: ./template
@@ -510,6 +511,27 @@ By default we ship some [built in actions](./builtin-actions.md) that you can
take a look at, or you can
[create your own custom actions](./writing-custom-actions.md).
When `each` is provided, the current iteration value is available in the `${{ each }}` input.
Examples:
```yaml
each: ['apples', 'oranges']
input:
values:
fruit: ${{ each.value }}
```
```yaml
each: [{ name: 'apple', count: 3 }, { name: 'orange', count: 1 }]
input:
values:
fruit: ${{ each.value.name }}
count: ${{ each.value.count }}
```
When `each` is used, the outputs of a repeated step are returned as an array of outputs from each iteration.
## Outputs
Each individual step can output some variables that can be used in the
+2 -5
View File
@@ -188,15 +188,12 @@ import {
} from '@backstage/plugin-techdocs';
import { Entity } from '@backstage/catalog-model';
import {
EntityListDocsGrid,
DocsGroupConfig,
} from '@backstage/plugin-techdocs';
import { EntityListDocsGrid } from '@backstage/plugin-techdocs';
export type CustomTechDocsHomeProps = {
groups?: Array<{
title: React.ReactNode;
filterPredicate: (entity: Entity) => boolean;
filterPredicate: ((entity: Entity) => boolean) | string;
}>;
};
+43 -13
View File
@@ -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
+12 -12
View File
@@ -2,25 +2,25 @@
id: glossary
title: Backstage Glossary
# prettier-ignore
description: List of all the terms, abbreviations, and phrases used in Backstage, together with their explanations.
description: List of terms, abbreviations, and phrases used in Backstage, together with their explanations.
---
The Backstage Glossary lists all the terms, abbreviations, and phrases used in
The Backstage Glossary lists terms, abbreviations, and phrases used in
Backstage, together with their explanations. We encourage you to use the
terminology below for clarity and consistency when discussing Backstage.
### Authentication Glossary
This [page](../auth/glossary.md) directs to the terms and phrases related to
authentication and identity section of Backstage.
See also [Authentication Glossary](../auth/glossary.md), a separate glossary of terms and phrases
specifically related to the authentication and identity section of Backstage.
### Backstage User Profiles
There are three main user profiles for Backstage: the integrator, the
contributor, and the software engineer.
contributor, and the end user (typically a software engineer).
| Term | Explanation |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Integrator | The **integrator** hosts the Backstage app and configures which plugins are available to use in the app. |
| Contributor | The **contributor** adds functionality to the app by writing plugins. |
| Software Engineer | The **software engineer** uses the app's functionality and interacts with its plugins. In practice, this profile covers the various roles that help deliver software, from the Software Engineer themselves, to Designers, Data Scientists, Product Owners, Engineering Managers, etc. |
| Term | Explanation |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Integrator | The **integrator** hosts the Backstage app and configures which plugins are available to use in the app. |
| Contributor | The **contributor** adds functionality to the app by writing plugins. |
| End user | The **end user** uses the app's functionality and interacts with its plugins. This profile covers the various roles that help deliver software. The typical end user is a **software engineer**, but users might also consider themselves _designers_, _data scientists_, _product owners_, _engineering managers_, _technical writers_, and so on. |
| Software engineer | The **software engineer** is an **end user** who uses the app's functionality and interacts with its plugins in the course of writing and documenting code. This user is more likely to embed documentation in the code files they produce, and create rough drafts of conceptual pages in collaboration with a **technical writer** or _technical editor_. |
| Technical writer | The **technical writer** is an **end user** who uses the app's functionality and interacts with its plugins in the course of writing and editing documentation. This user is more likely to produce and customize templates and produce conceptual pages to supplement documentation embedded in code files. |
@@ -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...
};
+16
View File
@@ -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.
+1 -1
View File
@@ -84,4 +84,4 @@ Below you can find a list of links and references to help you learn about and st
- [Changelog](https://github.com/backstage/backstage/tree/master/docs/releases/v1.16.0-changelog.md)
- Backstage [Demos](https://backstage.io/demos), [Blog](https://backstage.io/blog), [Roadmap](https://backstage.io/docs/overview/roadmap) and [Plugins](https://backstage.io/plugins)
Sign up for our [newsletter](https://mailchi.mp/spotify/backstage-community) if you want to be informed about what is happening in the world of Backstage.
Sign up for our [newsletter](https://info.backstage.spotify.com/newsletter_subscribe) if you want to be informed about what is happening in the world of Backstage.
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
+72
View File
@@ -0,0 +1,72 @@
---
id: v1.17.0
title: v1.17.0
description: Backstage Release v1.17.0
---
These are the release notes for the v1.17.0 release of [Backstage](https://backstage.io/).
A huge thanks to the whole team of maintainers and contributors as well as the amazing Backstage Community for the hard work in getting this release developed and done.
## Highlights
### Changes to the New Backend System
For this release we had another look at the new backend system, in particular how well it fits together with the concept of plugin installation without code modification, and we identified a number of breaking changes that we wanted to make.
We have removed the ability to define options for plugins and modules, and force them to be optional for services. Options have been moved either to static configuration or extension points, and modules now also have the ability to register extension points.
Service factories are now considered `BackendFeature`s and are installed via `backend.add(...)` rather than via the `services` option, which has been removed.
The configuration service has also been renamed to `rootConfig` in order to match other root-scoped services and make space for a potential plugin-scoped configuration service in the future.
The shared environments concept has been removed. We are still interested in having some way to define reusable presets in the new system, but shared environments were too limited.
We expect these to be the last broad breaking changes to the new backend system, and are likely to start encouraging use of it in the next release.
### Catalog Telemetry with Processing Tracing
The Catalog has been instrumented with some simple OpenTelemetry Spans so you can now dig into the processing loop and see it in action using tracing.
Contributed by [@mikebryant](https://github.com/mikebryant) in [#17534](https://github.com/backstage/backstage/pull/17534)
### New `each` property for Scaffolder Actions
You can now define an `each` iterable in the `steps` for a template, which will run a given action for each entry in the iterable.
Contributed by [@alexef](https://github.com/alexef) in [#18157](https://github.com/backstage/backstage/pull/18157)
### Updated proxy configuration
The shape of the proxy plugin configuration has been changed in order to make space for additional keys. Rather than defining the proxy endpoints directly under `proxy`, they should now be defined at `proxy.endpoints` instead.
### OpenAPI Support for Backend Plugins
You can now use OpenAPI specs to generate typed routers for your backend plugins with request validation using `createOpenApiRouter()`. Theres been some movement to support this for some of the plugins in the monorepo like `todo`, `search` and `catalog`.
Contributed by [@sennyeya](https://github.com/sennyeya) in [#17875](https://github.com/backstage/backstage/pull/17875)
### New plugin: `@backstage/plugin-catalog-backend-module-gcp`
Allows ingestion of GKE Clusters as Resources into the Catalog. Contributed by [@mclarke47](https://github.com/mclarke47) in [#18759](https://github.com/backstage/backstage/pull/18759)
## Security Fixes
This release does not contain any security fixes.
## Upgrade path
We recommend that you keep your Backstage project up to date with this latest release. For more guidance on how to upgrade, check out the documentation for [keeping Backstage updated](https://backstage.io/docs/getting-started/keeping-backstage-updated).
## Links and References
Below you can find a list of links and references to help you learn about and start using this new release.
- [Backstage official website](https://backstage.io/), [documentation](https://backstage.io/docs/), and [getting started guide](https://backstage.io/docs/getting-started/)
- [GitHub repository](https://github.com/backstage/backstage)
- Backstage's [versioning and support policy](https://backstage.io/docs/overview/versioning-policy)
- [Community Discord](https://discord.gg/backstage-687207715902193673) for discussions and support
- [Changelog](https://github.com/backstage/backstage/tree/master/docs/releases/v1.17.0-changelog.md)
- Backstage [Demos](https://backstage.io/demos), [Blog](https://backstage.io/blog), [Roadmap](https://backstage.io/docs/overview/roadmap) and [Plugins](https://backstage.io/plugins)
Sign up for our [newsletter](https://info.backstage.spotify.com/newsletter_subscribe) if you want to be informed about what is happening in the world of Backstage.
File diff suppressed because it is too large Load Diff