diff --git a/contrib/docs/tutorials/authenticate-api-requests.md b/contrib/docs/tutorials/authenticate-api-requests.md index 838aaffef6..8c858bea0f 100644 --- a/contrib/docs/tutorials/authenticate-api-requests.md +++ b/contrib/docs/tutorials/authenticate-api-requests.md @@ -3,8 +3,7 @@ > [!CAUTION] > This entire guide MUST NOT BE USED by users of Backstage 1.26 and > newer. If you have applied the changes in this guide, you need to remove them -> again as you upgrade to recent versions of Backstage. When [the new auth -> changes](https://github.com/backstage/backstage/tree/master/beps/0003-auth-architecture-evolution) +> again as you upgrade to recent versions of Backstage. When [the new auth changes](https://github.com/backstage/backstage/tree/master/beps/0003-auth-architecture-evolution) > landed backends became natively secured through the framework, and the > instructions outlined in here can interfere with the backend functioning > correctly. diff --git a/contrib/docs/tutorials/aws-deployment.md b/contrib/docs/tutorials/aws-deployment.md index 6edbb73f9d..d43d8aefb0 100644 --- a/contrib/docs/tutorials/aws-deployment.md +++ b/contrib/docs/tutorials/aws-deployment.md @@ -1,11 +1,9 @@ # Deploying Backstage on AWS using ECR and EKS -Backstage documentation shows how to build a [Docker -image](https://backstage.io/docs/deployment/docker); this +Backstage documentation shows how to build a [Docker image](https://backstage.io/docs/deployment/docker); this tutorial shows how to deploy that Docker image to AWS using Elastic Container Registry (ECR) and Elastic Kubernetes Service (EKS). Amazon also supports -deployments with Helm, covered in the [Helm -Kubernetes](../../kubernetes/basic_kubernetes_example_with_helm) example. +deployments with Helm, covered in the [Helm Kubernetes](../../kubernetes/basic_kubernetes_example_with_helm) example. The basic workflow for this method is to build a Backstage Docker image, upload the new version to a container registry, and update a Kubernetes deployment with @@ -13,8 +11,7 @@ the new image. ## Create a container registry -To create an Elastic Container Registry on AWS, go to the [AWS ECR -console](https://console.aws.amazon.com/ecr/repositories). +To create an Elastic Container Registry on AWS, go to the [AWS ECR console](https://console.aws.amazon.com/ecr/repositories). Click `Create repository` and give the repository a name, like `backstage`. @@ -35,8 +32,7 @@ Go to [AWS IAM console](https://console.aws.amazon.com/iam/home) and select ## Publish a Backstage build -Follow the [Docker -image](https://backstage.io/docs/deployment/docker) +Follow the [Docker image](https://backstage.io/docs/deployment/docker) documentation to build a new Backstage Docker image: ```shell @@ -56,8 +52,7 @@ Default region name: Now you can use the AWS CLI to push the built image to the ECR repository. It's a good practice to use a specific version tag as well as `latest` when pushing; -more about [Semver tagging -here](https://medium.com/@mccode/using-semantic-versioning-for-docker-image-tags-dfde8be06699). +more about [Semver tagging here](https://medium.com/@mccode/using-semantic-versioning-for-docker-image-tags-dfde8be06699). Go to the [AWS ECR console](https://console.aws.amazon.com/ecr/repositories) and click on your repository, then `View push commands`. This will show the @@ -83,12 +78,10 @@ Kubernetes deployment based on this image. Creating an Elastic Kubernetes Service (EKS) cluster is beyond the scope of this document, but it can be as easy as `eksctl create cluster` documented in the -[AWS EKS getting started -guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html), +[AWS EKS getting started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html), which uses a Cloudformation template to create the necessary resources. -To deploy the Docker image to EKS, follow the [Kubernetes -guide](https://backstage.io/docs/deployment/k8s#creating-the-backstage-instance) +To deploy the Docker image to EKS, follow the [Kubernetes guide](https://backstage.io/docs/deployment/k8s#creating-the-backstage-instance) but set the Backstage deployment `image` to the ECR repository URL: ```yaml @@ -110,8 +103,7 @@ spec: ... ``` -Create the [Service -descriptor](https://backstage.io/docs/deployment/k8s#creating-a-backstage-service) +Create the [Service descriptor](https://backstage.io/docs/deployment/k8s#creating-a-backstage-service) as well, and apply these Kubernetes definitions to the EKS cluster to complete the Backstage deployment: @@ -120,16 +112,14 @@ $ kubectl apply -f kubernetes/backstage.yaml $ kubectl apply -f kubernetes/backstage-service.yaml ``` -Now you can see your Backstage workload running from the [EKS -console](https://console.aws.amazon.com/eks/home). +Now you can see your Backstage workload running from the [EKS console](https://console.aws.amazon.com/eks/home). ## Further steps ### Exposing Backstage with a load balancer To make the service useful, we need to expose the workload with a load balancer. -Follow the [Application load balancing on -EKS](https://docs.aws.amazon.com/eks/latest/userguide/alb-ingress.html) guide to +Follow the [Application load balancing on EKS](https://docs.aws.amazon.com/eks/latest/userguide/alb-ingress.html) guide to set up a Load Balancer controller and Kubernetes ingress to your application. This is ultimately a `kubectl apply` with an ingress definition: diff --git a/docs/auth/cloudflare/access.md b/docs/auth/cloudflare/access.md index 9df816c39f..52d9fdfc21 100644 --- a/docs/auth/cloudflare/access.md +++ b/docs/auth/cloudflare/access.md @@ -170,6 +170,5 @@ backend.add(customAuth); The body of the sign-in resolver is up to you to write! The example code above is just a copy of what `emailMatchingUserEntityProfileEmail` does. The `info` parameter contains all of the results of the sign-in attempt so far. The `ctx` -context [has several useful -functions](https://backstage.io/docs/reference/plugin-auth-node.authresolvercontext/) +context [has several useful functions](https://backstage.io/docs/reference/plugin-auth-node.authresolvercontext/) for issuing tokens in various ways. diff --git a/docs/auth/identity-resolver.md b/docs/auth/identity-resolver.md index 406f789630..4140276df8 100644 --- a/docs/auth/identity-resolver.md +++ b/docs/auth/identity-resolver.md @@ -5,8 +5,7 @@ description: An introduction to Backstage user identities and sign-in resolvers --- :::info -This documentation is written for [the new backend -system](../backend-system/index.md) which is the default since Backstage +This documentation is written for [the new backend system](../backend-system/index.md) which is the default since Backstage [version 1.24](../releases/v1.24.0.md). If you are still on the old backend system, you may want to read [its own article](./identity-resolver--old.md) instead, and [consider migrating](../backend-system/building-backends/08-migrating.md)! @@ -31,15 +30,13 @@ testing purposes and quickly getting started locally, but is not safe for use in production and that particular provider will refuse to work there. Because of this, one of the early things you want to do when standing up your -Backstage instance is to choose a production ready auth provider. See [the auth -overview page](./index.md) for a full list of providers and how to install and +Backstage instance is to choose a production ready auth provider. See [the auth overview page](./index.md) for a full list of providers and how to install and configure them. ## Backstage User Identity A user identity within Backstage is built up from two main pieces of -information: a user [entity -reference](../features/software-catalog/references.md), and a set of ownership +information: a user [entity reference](../features/software-catalog/references.md), and a set of ownership references. When a user signs in, a Backstage token is generated which is then used to identify the user within the Backstage ecosystem. @@ -194,8 +191,7 @@ backend.add(import('@backstage/plugin-auth-backend-module-github-provider')); backend.add(customAuth); ``` -Check out [the naming patterns -article](../backend-system/architecture/07-naming-patterns.md) for what rules +Check out [the naming patterns article](../backend-system/architecture/07-naming-patterns.md) for what rules apply regarding how to form valid IDs. In this example we also put the module declaration directly in `packages/backend/src/index.ts` but that's just for simplicity. You can place it anywhere you like, including in other packages, and @@ -244,8 +240,7 @@ async signInResolver(info, ctx) { If you throw an error in the sign in resolver function, the sign in attempt is immediately rejected, and the error details are presented in the user interface. -The `ctx` context [has several useful -functions](https://backstage.io/docs/reference/plugin-auth-node.authresolvercontext/) +The `ctx` context [has several useful functions](https://backstage.io/docs/reference/plugin-auth-node.authresolvercontext/) for issuing tokens in various ways. ### Custom Ownership Resolution diff --git a/docs/auth/microsoft/provider.md b/docs/auth/microsoft/provider.md index 5c4707c151..ab3c5d8044 100644 --- a/docs/auth/microsoft/provider.md +++ b/docs/auth/microsoft/provider.md @@ -103,6 +103,5 @@ hosts: - `login.microsoftonline.com`, to get and exchange authorization codes and access tokens - `graph.microsoft.com`, to fetch user profile information (as seen - in [this source - code](https://github.com/seanfisher/passport-microsoft/blob/0456aa9bce05579c18e77f51330176eb26373658/lib/strategy.js#L93-L95)). + in [this source code](https://github.com/seanfisher/passport-microsoft/blob/0456aa9bce05579c18e77f51330176eb26373658/lib/strategy.js#L93-L95)). If this host is unreachable, users may see an `Authentication failed, failed to fetch user profile` error when they attempt to log in. diff --git a/docs/auth/service-to-service-auth.md b/docs/auth/service-to-service-auth.md index c1d6643769..c08411aca5 100644 --- a/docs/auth/service-to-service-auth.md +++ b/docs/auth/service-to-service-auth.md @@ -6,8 +6,7 @@ description: This section describes service to service authentication works, bot --- :::info -This documentation is written for [the new backend -system](../backend-system/index.md) which is the default since Backstage +This documentation is written for [the new backend system](../backend-system/index.md) which is the default since Backstage [version 1.24](../releases/v1.24.0.md). If you are still on the old backend system, you may want to read [its own article](./service-to-service-auth--old.md) instead, and [consider migrating](../backend-system/building-backends/08-migrating.md)! diff --git a/docs/auth/vmware-cloud/provider.md b/docs/auth/vmware-cloud/provider.md index 0ff928ab7f..d7580eccba 100644 --- a/docs/auth/vmware-cloud/provider.md +++ b/docs/auth/vmware-cloud/provider.md @@ -12,14 +12,11 @@ Cloud Console and within a Backstage app required to enable this capability. ## Create an OAuth App in the VMware Cloud Console 1. Log in to the [VMware Cloud Console](https://console.cloud.vmware.com). -1. Navigate to [Identity & Access Management > OAuth - Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps) - and click the [Owned - Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps/owned-apps/view) +1. Navigate to [Identity & Access Management > OAuth Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps) + and click the [Owned Apps](https://console.cloud.vmware.com/csp/gateway/portal/#/consumer/usermgmt/oauth-apps/owned-apps/view) tab -- if you are not an Organization Owner or Administrator but only a Member, you will not see this nav entry unless the **Developer** check box is - selected for your role (see the [Organization roles and - permissions](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-C11D3AAC-267C-4F16-A0E3-3EDF286EBE53.html#organization-roles-and-permissions-0) + selected for your role (see the [Organization roles and permissions](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-C11D3AAC-267C-4F16-A0E3-3EDF286EBE53.html#organization-roles-and-permissions-0) docs for details). 1. Click **Create App**, choose 'Web/Mobile app' and click **Continue**. 1. Use default settings except: @@ -161,8 +158,7 @@ auth: ``` Where `APP_ID` refers to the ID retrieved when creating the OAuth App, and -`ORG_ID` is the [long ID of the -Organization](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-CF9E9318-B811-48CF-8499-9419997DC1F8.html#view-the-organization-id-1) +`ORG_ID` is the [long ID of the Organization](https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-CF9E9318-B811-48CF-8499-9419997DC1F8.html#view-the-organization-id-1) in VMware Cloud for which you wish to enable sign-in. Note that VMware Cloud requires OAuth Apps to use diff --git a/docs/backend-system/building-plugins-and-modules/01-index.md b/docs/backend-system/building-plugins-and-modules/01-index.md index 168646afab..1aa8b140ed 100644 --- a/docs/backend-system/building-plugins-and-modules/01-index.md +++ b/docs/backend-system/building-plugins-and-modules/01-index.md @@ -73,8 +73,7 @@ items. Backend modules are used to extend [plugins](../architecture/04-plugins.md) or other modules with additional features or change existing behavior. They must always be installed in the same backend instance as the plugin or module that they extend, and may only extend a single plugin and modules from that plugin at a time. -Modules interact with their target plugin or module using the [extension -points](../architecture/05-extension-points.md) registered by the plugin, while also being +Modules interact with their target plugin or module using the [extension points](../architecture/05-extension-points.md) registered by the plugin, while also being able to depend on the [services](../architecture/03-services.md) of the target plugin. That last point is worth reiterating: injected `plugin` scoped services will be the exact @@ -157,8 +156,7 @@ the database. They will run on the same logical database instance as the target plugin, so care must be taken to choose table names that do not risk colliding with those of the plugin. A recommended naming pattern is `__`, for example the `@backstage/backend-tasks` package creates -tables named `backstage_backend_tasks__
`. If you use the default [`Knex` -migration facilities](https://knexjs.org/guide/migrations.html), you will also +tables named `backstage_backend_tasks__
`. If you use the default [`Knex` migration facilities](https://knexjs.org/guide/migrations.html), you will also want to make sure that it uses similarly prefixed migration state tables for its internal bookkeeping needs, so they do not collide with the main ones used by the plugin itself. You can do this as follows: @@ -179,8 +177,7 @@ There are several ways of configuring and customizing plugins and modules. Whenever you want to allow modules to configure your plugin dynamically, for example in the way that the catalog backend lets catalog modules inject additional entity providers, you can use the extension points mechanism. This is -described in detail with code examples in [the extension points architecture -article](../architecture/05-extension-points.md), while the following is a more +described in detail with code examples in [the extension points architecture article](../architecture/05-extension-points.md), while the following is a more slim example of how to implement an extension point for a plugin: ```ts @@ -249,7 +246,5 @@ export const examplePlugin = createBackendPlugin({ }); ``` -Before adding custom configuration options, make sure to read [the configuration -docs](../../conf/index.md), in particular the section on [defining configuration -for your own plugins](../../conf/defining.md) which explains how to establish a +Before adding custom configuration options, make sure to read [the configuration docs](../../conf/index.md), in particular the section on [defining configuration for your own plugins](../../conf/defining.md) which explains how to establish a configuration schema for your specific plugin. diff --git a/docs/backend-system/building-plugins-and-modules/02-testing.md b/docs/backend-system/building-plugins-and-modules/02-testing.md index f8af2bcabe..8a2dd0414d 100644 --- a/docs/backend-system/building-plugins-and-modules/02-testing.md +++ b/docs/backend-system/building-plugins-and-modules/02-testing.md @@ -21,8 +21,7 @@ collective term for backend [plugins](../architecture/04-plugins.md) and The function returns an HTTP server instance which can be used together with e.g. `supertest` to easily test the actual REST service surfaces of plugins who -register routes with [the HTTP router service -API](../core-services/01-index.md). +register routes with [the HTTP router service API](../core-services/01-index.md). ```ts import { mockServices, startTestBackend } from '@backstage/backend-test-utils'; diff --git a/docs/features/kubernetes/configuration.md b/docs/features/kubernetes/configuration.md index 064f7c803c..0002e51160 100644 --- a/docs/features/kubernetes/configuration.md +++ b/docs/features/kubernetes/configuration.md @@ -198,8 +198,7 @@ in namespace `NAMESPACE` and it has adequate [permissions](#role-based-access-control), here are some sample procedures to procure a long-lived service account token for use with this provider: -- On versions of Kubernetes [prior to - 1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md#no-really-you-must-read-this-before-you-upgrade-1), +- On versions of Kubernetes [prior to 1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md#no-really-you-must-read-this-before-you-upgrade-1), you could get an (automatically-generated) token for a service account with: ```sh @@ -209,8 +208,7 @@ procure a long-lived service account token for use with this provider: | base64 --decode ``` -- For Kubernetes 1.24+, as described in [this - guide](https://kubernetes.io/docs/concepts/configuration/secret/#service-account-token-secrets), +- For Kubernetes 1.24+, as described in [this guide](https://kubernetes.io/docs/concepts/configuration/secret/#service-account-token-secrets), you can obtain a long-lived token by creating a secret: ```sh @@ -235,8 +233,7 @@ procure a long-lived service account token for use with this provider: If a cluster has `authProvider: serviceAccount` and the `serviceAccountToken` field is omitted, Backstage will ignore the configured URL and certificate data, instead attempting to access the Kubernetes API via an in-cluster client as in -[this -example](https://github.com/kubernetes-client/javascript/blob/master/examples/in-cluster.js). +[this example](https://github.com/kubernetes-client/javascript/blob/master/examples/in-cluster.js). ##### `clusters.\*.oidcTokenProvider` (optional) diff --git a/docs/features/kubernetes/proxy.md b/docs/features/kubernetes/proxy.md index 4ccc2d22b1..2da797d8ef 100644 --- a/docs/features/kubernetes/proxy.md +++ b/docs/features/kubernetes/proxy.md @@ -7,12 +7,10 @@ description: Interacting with the Kubernetes API in Backstage plugins [Contributors](https://backstage.io/docs/overview/glossary#backstage-user-profiles) wanting to create developer portal experiences based on data from Kubernetes (e.g. for -interacting with [Custom -Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) +interacting with [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) beyond the default behaviors of the existing Kubernetes plugin) can leverage the Kubernetes backend plugin's proxy endpoint to allow them to make arbitrary -requests to the [REST -API](https://kubernetes.io/docs/reference/using-api/api-concepts/). +requests to the [REST API](https://kubernetes.io/docs/reference/using-api/api-concepts/). Here is a snippet fetching namespaces using the `KubernetesBackendClient` library @@ -31,8 +29,7 @@ await kubernetesApi.proxy(CLUSTER_NAME, '/api/v1/namespaces'); The proxy will interpret the [`Backstage-Kubernetes-Cluster`](https://backstage.io/docs/reference/plugin-kubernetes-backend.header_kubernetes_cluster) header as the name of the cluster to target. This name will be compared to each cluster -returned by all the configured [cluster -locators](https://backstage.io/docs/features/kubernetes/configuration#clusterlocatormethods) +returned by all the configured [cluster locators](https://backstage.io/docs/features/kubernetes/configuration#clusterlocatormethods) -- the first cluster whose [`name` field](https://backstage.io/docs/features/kubernetes/configuration#clustersname) matches the value in the header will be targeted. @@ -48,12 +45,10 @@ The proxy expects a `KubernetesAuthTranslator` to be provided that is used to de ## Authentication The proxy has no provisions for mTLS, so it cannot be used to connect to -clusters using the [x509 Client -Certs](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#x509-client-certs) +clusters using the [x509 Client Certs](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#x509-client-certs) authentication strategy.\ The current `/proxy` Implementation expects a -[Bearer -token](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#putting-a-bearer-token-in-a-request) +[Bearer token](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#putting-a-bearer-token-in-a-request) to be provided as a `Backstage-Kubernetes-Authorization` header for a target cluster. This token will be used as the `Authorization` header when forwarding a request to a target cluster. ## How to disable the proxy endpoint via PermissionPolicy @@ -104,8 +99,7 @@ even if a valid ID token was attached that a cluster would authorize. ## Other known limitations -The proxy as it was released in [Backstage -1.9](https://github.com/backstage/backstage/blob/master/docs/releases/v1.9.0-changelog.md#patch-changes-15) +The proxy as it was released in [Backstage 1.9](../../releases/v1.9.0-changelog.md#patch-changes-15) has a known bug: - [#15901](https://github.com/backstage/backstage/issues/15901) - it cannot diff --git a/docs/features/software-catalog/index.md b/docs/features/software-catalog/index.md index c98d6911b4..a65bfb4a44 100644 --- a/docs/features/software-catalog/index.md +++ b/docs/features/software-catalog/index.md @@ -40,8 +40,7 @@ browse the catalog at `http://localhost:3000`. ## Adding components to the catalog -The source of truth for the components in your software catalog are [metadata -YAML files](descriptor-format.md) stored in source control (GitHub, GitHub +The source of truth for the components in your software catalog are [metadata YAML files](descriptor-format.md) stored in source control (GitHub, GitHub Enterprise, GitLab, ...). Repositories can include one or multiple metadata files. Usually the metadata file is located in the repository root. This is not a formal requirement & metadata files can be placed anywhere in the repository. diff --git a/docs/integrations/github/org--old.md b/docs/integrations/github/org--old.md index 2f1b39a1f8..3d1639a924 100644 --- a/docs/integrations/github/org--old.md +++ b/docs/integrations/github/org--old.md @@ -308,8 +308,7 @@ const githubOrgProvider = GithubOrgEntityProvider.fromConfig(env.config, { }); ``` -Once you have imported the emails you can resolve users in your [sign-in -resolver](../../auth/github/provider.md) using the catalog entity search via email +Once you have imported the emails you can resolve users in your [sign-in resolver](../../auth/github/provider.md) using the catalog entity search via email ```typescript title="packages/backend/src/plugins/auth.ts" ctx.signInWithCatalogUser({ diff --git a/docs/overview/roadmap.md b/docs/overview/roadmap.md index 8e3d73ded6..186619d1df 100644 --- a/docs/overview/roadmap.md +++ b/docs/overview/roadmap.md @@ -10,8 +10,7 @@ Backstage is currently under rapid development. This page details the project's public roadmap, the result of ongoing collaboration between the core maintainers and the broader Backstage community. -The Backstage roadmap lays out both [“what's next”](#whats-next) and ["future -work"](#future-work). With "next" we mean features planned for release within +The Backstage roadmap lays out both [“what's next”](#whats-next) and ["future work"](#future-work). With "next" we mean features planned for release within the ongoing quarter from July through September 2022. With "future" we mean features on the radar, but not yet scheduled. @@ -52,8 +51,7 @@ the platform. The benefit for the adopters is clear: we want Backstage to be as secure as possible, and we want to make it reliable through a specific initiative. -This initiative is done together with, and with the support of, the [Cloud -Native Computing Foundation (CNCF)](https://www.cncf.io/). +This initiative is done together with, and with the support of, the [Cloud Native Computing Foundation (CNCF)](https://www.cncf.io/). ### Backstage Threat Model diff --git a/docs/plugins/analytics.md b/docs/plugins/analytics.md index 52a859b5e9..10a7421057 100644 --- a/docs/plugins/analytics.md +++ b/docs/plugins/analytics.md @@ -69,8 +69,7 @@ installed, may be captured. | `discover` | The title of the search result that was clicked on | The `value` is the result rank. A `to` attribute is also provided. | | `not-found` | The path of the resource that resulted in a not found page | Fired by at least TechDocs. | -If there is an event you'd like to see captured, please [open an -issue](https://github.com/backstage/backstage/issues/new?assignees=&labels=enhancement&template=feature_template.md&title=[Analytics%20Event]:%20THE+EVENT+TO+CAPTURE) describing the event you want to see and the questions it +If there is an event you'd like to see captured, please [open an issue](https://github.com/backstage/backstage/issues/new?assignees=&labels=enhancement&template=feature_template.md&title=[Analytics%20Event]:%20THE+EVENT+TO+CAPTURE) describing the event you want to see and the questions it would help you answer. Or jump to [Capturing Events](#capturing-events) to learn how to contribute the instrumentation yourself! diff --git a/docs/releases/v1.12.0-changelog.md b/docs/releases/v1.12.0-changelog.md index df25020aee..49ff79d19a 100644 --- a/docs/releases/v1.12.0-changelog.md +++ b/docs/releases/v1.12.0-changelog.md @@ -60,8 +60,7 @@ This change makes the dependence explicit, and removes the burden on OAuth2-based providers which require an ID token (e.g. this is done by various - default [auth - handlers](https://backstage.io/docs/auth/identity-resolver/#authhandler)) to add + default [auth handlers](https://backstage.io/docs/auth/identity-resolver/#authhandler)) to add `openid` to their default scopes. _That_ could carry another indirect benefit: by removing `openid` from the default scopes for a provider, grants for resource-specific access tokens can avoid requesting excess ID token-related diff --git a/docs/releases/v1.12.0-next.2-changelog.md b/docs/releases/v1.12.0-next.2-changelog.md index 7a64ec5f84..ed4c5683ba 100644 --- a/docs/releases/v1.12.0-next.2-changelog.md +++ b/docs/releases/v1.12.0-next.2-changelog.md @@ -25,8 +25,7 @@ This change makes the dependence explicit, and removes the burden on OAuth2-based providers which require an ID token (e.g. this is done by various - default [auth - handlers](https://backstage.io/docs/auth/identity-resolver/#authhandler)) to add + default [auth handlers](https://backstage.io/docs/auth/identity-resolver/#authhandler)) to add `openid` to their default scopes. _That_ could carry another indirect benefit: by removing `openid` from the default scopes for a provider, grants for resource-specific access tokens can avoid requesting excess ID token-related diff --git a/docs/releases/v1.15.0.md b/docs/releases/v1.15.0.md index 336fe7520b..c7ef6b33f9 100644 --- a/docs/releases/v1.15.0.md +++ b/docs/releases/v1.15.0.md @@ -27,8 +27,7 @@ native dependency, and as such needs to be built during `yarn` installation, on the exact architecture that it then executes on. For those who compile and run Backstage on stripped-down environments, you will want to ensure that you have the build basics present, e.g. `build-essential` or similar corresponding to -your operating system of choice. The `isolated-vm` repo has [some further -information](https://github.com/laverdet/isolated-vm#requirements) about the +your operating system of choice. The `isolated-vm` repo has [some further information](https://github.com/laverdet/isolated-vm#requirements) about the build environment requirements. There is a [CVE-2022-39266](https://www.cve.org/CVERecord?id=CVE-2022-39266) @@ -65,8 +64,7 @@ covers of your catalog instance, finding those pesky unprocessed entities that may be stuck in limbo because of an otherwise tricky-to-debug validation issue or similar. -Check out [the plugin’s -README](https://github.com/backstage/backstage/blob/master/plugins/catalog-unprocessed-entities/README.md) +Check out [the plugin’s README](https://github.com/backstage/backstage/blob/master/plugins/catalog-unprocessed-entities/README.md) for details and installation instructions. Contributed by [@alde](https://github.com/alde) in @@ -176,8 +174,7 @@ Contributed by [@sblausten](https://github.com/sblausten) in 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). +[keeping Backstage updated](https://backstage.io/docs/getting-started/keeping-backstage-updated). ## Links and References @@ -185,11 +182,9 @@ 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/) + [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) +- 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.15.0-changelog.md) diff --git a/docs/releases/v1.3.0-changelog.md b/docs/releases/v1.3.0-changelog.md index 641fd8422a..e3cdd75024 100644 --- a/docs/releases/v1.3.0-changelog.md +++ b/docs/releases/v1.3.0-changelog.md @@ -883,8 +883,7 @@ ### Patch Changes - 8f7b1835df: Updated dependency `msw` to `^0.41.0`. -- 811ff4bcf4: Updated `swagger-ui-react` to 4.11.1 in order to address a [XSS - vulnerability](https://github.com/advisories/GHSA-hqq7-2q2v-82xq) in `@braintree/sanitize-url` +- 811ff4bcf4: Updated `swagger-ui-react` to 4.11.1 in order to address a [XSS vulnerability](https://github.com/advisories/GHSA-hqq7-2q2v-82xq) in `@braintree/sanitize-url` - Updated dependencies - @backstage/plugin-catalog@1.3.0 - @backstage/plugin-catalog-react@1.1.1 diff --git a/docs/releases/v1.7.0-changelog.md b/docs/releases/v1.7.0-changelog.md index 3653484952..47fd8463d6 100644 --- a/docs/releases/v1.7.0-changelog.md +++ b/docs/releases/v1.7.0-changelog.md @@ -926,8 +926,7 @@ Migrating to the stable version of `react-router` is optional for the time being. But if you want to do the same for your existing repository, please - follow [this - guide](https://backstage.io/docs/tutorials/react-router-stable-migration). + follow [this guide](https://backstage.io/docs/tutorials/react-router-stable-migration). - e05e0f021b: Update versions of packages used in the create-app template, to match those in the main repo diff --git a/docs/releases/v1.7.0-next.0-changelog.md b/docs/releases/v1.7.0-next.0-changelog.md index 57b3c64f6f..41d3ebd55f 100644 --- a/docs/releases/v1.7.0-next.0-changelog.md +++ b/docs/releases/v1.7.0-next.0-changelog.md @@ -319,8 +319,7 @@ Migrating to the stable version of `react-router` is optional for the time being. But if you want to do the same for your existing repository, please - follow [this - guide](https://backstage.io/docs/tutorials/react-router-stable-migration). + follow [this guide](https://backstage.io/docs/tutorials/react-router-stable-migration). - e05e0f021b: Update versions of packages used in the create-app template, to match those in the main repo diff --git a/docs/releases/v1.7.0.md b/docs/releases/v1.7.0.md index 56eda8b20d..edd5cbb591 100644 --- a/docs/releases/v1.7.0.md +++ b/docs/releases/v1.7.0.md @@ -22,24 +22,20 @@ backend needs to be supplied with a location analyzer for this use case to continue to function. If you want to make use of this feature, check out the installation instructions -in [the -changelog](https://github.com/backstage/backstage/blob/master/plugins/catalog-import/CHANGELOG.md#090). +in [the changelog](https://github.com/backstage/backstage/blob/master/plugins/catalog-import/CHANGELOG.md#090). Contributed by [@kissmikijr](https://github.com/kissmikijr) in [#13800](https://github.com/backstage/backstage/pull/13800) ### Permission Rule Changes -When defining permission rules, it's now necessary to provide a [Zod -Schema](https://github.com/colinhacks/zod) that specifies the parameters the +When defining permission rules, it's now necessary to provide a [Zod Schema](https://github.com/colinhacks/zod) that specifies the parameters the rule expects. This has been added to help better describe the parameters in the response of the metadata endpoint and to validate the parameters before a rule is executed. The signatures of the rule methods (`apply` and `toQuery`) have changed slightly as well. -You can read more about this in [the permissions -documentation](https://backstage.io/docs/permissions/overview) and [the -changelog](https://github.com/backstage/backstage/blob/master/plugins/permission-node/CHANGELOG.md#070). +You can read more about this in [the permissions documentation](https://backstage.io/docs/permissions/overview) and [the changelog](https://github.com/backstage/backstage/blob/master/plugins/permission-node/CHANGELOG.md#070). ### Migration: `jest` v29 @@ -64,8 +60,7 @@ Newly created Backstage repositories now use the stable version 6 of Migrating to the stable version of `react-router` is optional for the time being; Backstage has support for both versions. But if you want to do the same -for your existing repository, please follow [this -guide](https://backstage.io/docs/tutorials/react-router-stable-migration). +for your existing repository, please follow [this guide](https://backstage.io/docs/tutorials/react-router-stable-migration). Support for the beta version will be removed in a later release. ### Support for `__mocks__` and `__testUtils__` directories @@ -100,8 +95,7 @@ This release does not contain any security fixes. 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). +[keeping Backstage updated](https://backstage.io/docs/getting-started/keeping-backstage-updated). ## Links and References @@ -109,11 +103,9 @@ 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/) + [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) +- 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.7.0-changelog.md) - Backstage [Demos](https://backstage.io/demos), diff --git a/packages/core-app-api/CHANGELOG.md b/packages/core-app-api/CHANGELOG.md index c13bf1613e..f21eed47d0 100644 --- a/packages/core-app-api/CHANGELOG.md +++ b/packages/core-app-api/CHANGELOG.md @@ -539,8 +539,7 @@ This change makes the dependence explicit, and removes the burden on OAuth2-based providers which require an ID token (e.g. this is done by various - default [auth - handlers](https://backstage.io/docs/auth/identity-resolver/#authhandler)) to add + default [auth handlers](https://backstage.io/docs/auth/identity-resolver/#authhandler)) to add `openid` to their default scopes. _That_ could carry another indirect benefit: by removing `openid` from the default scopes for a provider, grants for resource-specific access tokens can avoid requesting excess ID token-related @@ -568,8 +567,7 @@ This change makes the dependence explicit, and removes the burden on OAuth2-based providers which require an ID token (e.g. this is done by various - default [auth - handlers](https://backstage.io/docs/auth/identity-resolver/#authhandler)) to add + default [auth handlers](https://backstage.io/docs/auth/identity-resolver/#authhandler)) to add `openid` to their default scopes. _That_ could carry another indirect benefit: by removing `openid` from the default scopes for a provider, grants for resource-specific access tokens can avoid requesting excess ID token-related diff --git a/packages/create-app/CHANGELOG.md b/packages/create-app/CHANGELOG.md index b301828207..ee49b7d8f5 100644 --- a/packages/create-app/CHANGELOG.md +++ b/packages/create-app/CHANGELOG.md @@ -1134,8 +1134,7 @@ Migrating to the stable version of `react-router` is optional for the time being. But if you want to do the same for your existing repository, please - follow [this - guide](https://backstage.io/docs/tutorials/react-router-stable-migration). + follow [this guide](https://backstage.io/docs/tutorials/react-router-stable-migration). - e05e0f021b: Update versions of packages used in the create-app template, to match those in the main repo - 01dff06be4: Leverage cache mounts in Dockerfile during `yarn install ...` and `apt-get ...` commands to speed up repeated builds. @@ -1182,8 +1181,7 @@ Migrating to the stable version of `react-router` is optional for the time being. But if you want to do the same for your existing repository, please - follow [this - guide](https://backstage.io/docs/tutorials/react-router-stable-migration). + follow [this guide](https://backstage.io/docs/tutorials/react-router-stable-migration). - e05e0f021b: Update versions of packages used in the create-app template, to match those in the main repo - 52f25858a8: Added `*.session.sql` Visual Studio Code database functionality files to `.gitignore` in the default template. This is optional but potentially helpful if your developers use Visual Studio Code; you can add a line with that exact value to your own root `.gitignore` if you want the same. @@ -3166,8 +3164,7 @@ The old `sqlite3` NPM library has been abandoned by its maintainers, which has led to unhandled security reports and other issues. Therefore, in the `knex` 1.x - release line they have instead switched over to the [`@vscode/sqlite3` - library](https://github.com/microsoft/vscode-node-sqlite3) by default, which is + release line they have instead switched over to the [`@vscode/sqlite3` library](https://github.com/microsoft/vscode-node-sqlite3) by default, which is actively maintained by Microsoft. This means that as you update to this version of Backstage, there are two @@ -3236,8 +3233,7 @@ The old `sqlite3` NPM library has been abandoned by its maintainers, which has led to unhandled security reports and other issues. Therefore, in the `knex` 1.x - release line they have instead switched over to the [`@vscode/sqlite3` - library](https://github.com/microsoft/vscode-node-sqlite3) by default, which is + release line they have instead switched over to the [`@vscode/sqlite3` library](https://github.com/microsoft/vscode-node-sqlite3) by default, which is actively maintained by Microsoft. This means that as you update to this version of Backstage, there are two diff --git a/plugins/api-docs/CHANGELOG.md b/plugins/api-docs/CHANGELOG.md index 39613bd409..24b30e2fda 100644 --- a/plugins/api-docs/CHANGELOG.md +++ b/plugins/api-docs/CHANGELOG.md @@ -1349,8 +1349,7 @@ ### Patch Changes - 8f7b1835df: Updated dependency `msw` to `^0.41.0`. -- 811ff4bcf4: Updated `swagger-ui-react` to 4.11.1 in order to address a [XSS - vulnerability](https://github.com/advisories/GHSA-hqq7-2q2v-82xq) in `@braintree/sanitize-url` +- 811ff4bcf4: Updated `swagger-ui-react` to 4.11.1 in order to address a [XSS vulnerability](https://github.com/advisories/GHSA-hqq7-2q2v-82xq) in `@braintree/sanitize-url` - Updated dependencies - @backstage/plugin-catalog@1.3.0 - @backstage/plugin-catalog-react@1.1.1 diff --git a/plugins/catalog-backend/CHANGELOG.md b/plugins/catalog-backend/CHANGELOG.md index 4d8e2f1cd0..cb4e25d190 100644 --- a/plugins/catalog-backend/CHANGELOG.md +++ b/plugins/catalog-backend/CHANGELOG.md @@ -3574,8 +3574,7 @@ `packages/backend/src/plugins/catalog.ts` creates the catalog builder using `CatalogBuilder.create`. If you instead call `new CatalogBuilder`, you are on the old implementation and will experience breakage if you upgrade to this - version. If you are still on the old version, see [the relevant change log - entry](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/CHANGELOG.md#patch-changes-27) + version. If you are still on the old version, see [the relevant change log entry](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/CHANGELOG.md#patch-changes-27) for migration instructions. The minimal `packages/backend/src/plugins/catalog.ts` file is now: @@ -3668,8 +3667,7 @@ `packages/backend/src/plugins/catalog.ts` creates the catalog builder using `CatalogBuilder.create`. If you instead call `new CatalogBuilder`, you are on the old implementation and will experience breakage if you upgrade to this - version. If you are still on the old version, see [the relevant change log - entry](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/CHANGELOG.md#patch-changes-27) + version. If you are still on the old version, see [the relevant change log entry](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/CHANGELOG.md#patch-changes-27) for migration instructions. The minimal `packages/backend/src/plugins/catalog.ts` file is now: diff --git a/plugins/catalog-backend/README.md b/plugins/catalog-backend/README.md index 7f886de155..c2fbe713b9 100644 --- a/plugins/catalog-backend/README.md +++ b/plugins/catalog-backend/README.md @@ -1,9 +1,7 @@ # Catalog Backend -This is the backend for the default Backstage [software -catalog](http://backstage.io/docs/features/software-catalog/). -This provides an API for consumers such as the frontend [catalog -plugin](https://github.com/backstage/backstage/tree/master/plugins/catalog). +This is the backend for the default Backstage [software catalog](http://backstage.io/docs/features/software-catalog/). +This provides an API for consumers such as the frontend [catalog plugin](https://github.com/backstage/backstage/tree/master/plugins/catalog). It comes with a builtin database-backed implementation of the catalog that can store and serve your catalog for you. @@ -34,8 +32,7 @@ yarn --cwd packages/backend add @backstage/plugin-catalog-backend You'll need to add the plugin to the router in your `backend` package. You can do this by creating a file called `packages/backend/src/plugins/catalog.ts` with -contents matching [catalog.ts in the create-app -template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/packages/backend/src/plugins/catalog.ts). +contents matching [catalog.ts in the create-app template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/packages/backend/src/plugins/catalog.ts). With the `catalog.ts` router setup in place, add the router to `packages/backend/src/index.ts`: @@ -60,10 +57,8 @@ async function main() { ### Adding catalog entities At this point the `catalog-backend` is installed in your backend package, but -you will not have any catalog entities loaded. See [Catalog -Configuration](https://backstage.io/docs/features/software-catalog/configuration) -for how to add locations, or copy the catalog locations from the [create-app -template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/app-config.yaml.hbs) +you will not have any catalog entities loaded. See [Catalog Configuration](https://backstage.io/docs/features/software-catalog/configuration) +for how to add locations, or copy the catalog locations from the [create-app template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/app-config.yaml.hbs) to get up and running quickly. ## Development diff --git a/plugins/catalog-react/CHANGELOG.md b/plugins/catalog-react/CHANGELOG.md index fe64a6101d..bb2477302e 100644 --- a/plugins/catalog-react/CHANGELOG.md +++ b/plugins/catalog-react/CHANGELOG.md @@ -2945,8 +2945,7 @@ `CatalogPage` component in your `App.tsx` routing allows you to adjust the layout, header, and which filters are available. - See the documentation added on [Catalog - Customization](https://backstage.io/docs/features/software-catalog/catalog-customization) + See the documentation added on [Catalog Customization](https://backstage.io/docs/features/software-catalog/catalog-customization) for instructions. ### Patch Changes diff --git a/plugins/catalog/CHANGELOG.md b/plugins/catalog/CHANGELOG.md index d20331bbfe..abfcf1012c 100644 --- a/plugins/catalog/CHANGELOG.md +++ b/plugins/catalog/CHANGELOG.md @@ -3361,8 +3361,7 @@ `CatalogPage` component in your `App.tsx` routing allows you to adjust the layout, header, and which filters are available. - See the documentation added on [Catalog - Customization](https://backstage.io/docs/features/software-catalog/catalog-customization) + See the documentation added on [Catalog Customization](https://backstage.io/docs/features/software-catalog/catalog-customization) for instructions. ### Patch Changes diff --git a/plugins/catalog/README.md b/plugins/catalog/README.md index 1ce7b2bf69..9375c14a4a 100644 --- a/plugins/catalog/README.md +++ b/plugins/catalog/README.md @@ -1,7 +1,6 @@ # Backstage Catalog Frontend -This is the React frontend for the default Backstage [software -catalog](http://backstage.io/docs/features/software-catalog/). +This is the React frontend for the default Backstage [software catalog](http://backstage.io/docs/features/software-catalog/). This package supplies interfaces related to listing catalog entities or showing more information about them on entity pages. diff --git a/plugins/scaffolder-backend/README.md b/plugins/scaffolder-backend/README.md index 0aa57fd90c..c0629f24f0 100644 --- a/plugins/scaffolder-backend/README.md +++ b/plugins/scaffolder-backend/README.md @@ -1,9 +1,7 @@ # Scaffolder Backend -This is the backend for the default Backstage [software -templates](https://backstage.io/docs/features/software-templates/). -This provides the API for the frontend [scaffolder -plugin](https://github.com/backstage/backstage/tree/master/plugins/scaffolder), +This is the backend for the default Backstage [software templates](https://backstage.io/docs/features/software-templates/). +This provides the API for the frontend [scaffolder plugin](https://github.com/backstage/backstage/tree/master/plugins/scaffolder), as well as the built-in template actions, tasks and stages. ## Installation @@ -28,8 +26,7 @@ yarn --cwd packages/backend add @backstage/plugin-scaffolder-backend You'll need to add the plugin to the router in your `backend` package. You can do this by creating a file called `packages/backend/src/plugins/scaffolder.ts` -with contents matching [scaffolder.ts in the create-app -template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/packages/backend/src/plugins/scaffolder.ts). +with contents matching [scaffolder.ts in the create-app template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/packages/backend/src/plugins/scaffolder.ts). With the `scaffolder.ts` router setup in place, add the router to `packages/backend/src/index.ts`: @@ -54,10 +51,7 @@ async function main() { ### Adding templates At this point the scaffolder backend is installed in your backend package, but -you will not have any templates available to use. These need to be [added to the -software -catalog](https://backstage.io/docs/features/software-templates/adding-templates). +you will not have any templates available to use. These need to be [added to the software catalog](https://backstage.io/docs/features/software-templates/adding-templates). To get up and running and try out some templates quickly, you can or copy the -catalog locations from the [create-app -template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/app-config.yaml.hbs). +catalog locations from the [create-app template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/app-config.yaml.hbs). diff --git a/plugins/scaffolder-common/CHANGELOG.md b/plugins/scaffolder-common/CHANGELOG.md index 4a9e1b870b..9011c681cb 100644 --- a/plugins/scaffolder-common/CHANGELOG.md +++ b/plugins/scaffolder-common/CHANGELOG.md @@ -641,8 +641,7 @@ - e72d371296: Added `TemplateEntityV1beta2` which was moved here from `@backstage/plugin-scaffolder-common`. It has also been marked as deprecated in - the process - please consider [migrating to `v1beta3` - templates](https://backstage.io/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3). + the process - please consider [migrating to `v1beta3` templates](https://backstage.io/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3). - c77c5c7eb6: Added `backstage.role` to `package.json` - Updated dependencies - @backstage/catalog-model@0.10.0 diff --git a/plugins/scaffolder/README.md b/plugins/scaffolder/README.md index a6af441d62..8acf456b08 100644 --- a/plugins/scaffolder/README.md +++ b/plugins/scaffolder/README.md @@ -1,7 +1,6 @@ # Scaffolder Frontend -This is the React frontend for the default Backstage [software -templates](https://backstage.io/docs/features/software-templates/). +This is the React frontend for the default Backstage [software templates](https://backstage.io/docs/features/software-templates/). This package supplies interfaces related to showing available templates in the Backstage catalog and the workflow to create software using those templates. diff --git a/plugins/user-settings/README.md b/plugins/user-settings/README.md index 1ecaaeb536..41a6930ae3 100644 --- a/plugins/user-settings/README.md +++ b/plugins/user-settings/README.md @@ -8,8 +8,7 @@ This plugin provides two components, `` is intended to be used w It also provides a `UserSettingsStorage` implementation of the `StorageApi`, to be used in the frontend as a persistent alternative to the builtin `WebStorage`. -Please see [the backend -README](https://github.com/backstage/backstage/tree/master/plugins/user-settings-backend) +Please see [the backend README](https://github.com/backstage/backstage/tree/master/plugins/user-settings-backend) for installation instructions. ## Components Usage