+
+ );
+};
+```
+
+We use the `useRouteRef` hook to create a link generator function that returns the details page path. We then call the link generator, passing it an object with the kind, namespace, and name. These parameters are used to construct a concrete path to the "Foo" details page.
+
+Let's see how the details page can get the parameters from the URL:
+
+```tsx title="plugins/catalog/src/components/DetailsPage.tsx"
+import React from 'react';
+import { useRouteRefParams } from '@backstage/frontend-plugin-api';
+import { detailsRouteRef } from '../routes';
+
+export const DetailsPage = () => {
+ // highlight-next-line
+ const params = useRouteRefParams(detailsRouteRef);
+ return (
+ Index Page
+ + See "Foo" details + +
+
+ );
+};
+```
+
+In the code above, we are using the `useRouteRefParams` hook to retrieve the entity-composed id from the URL. The parameter object contains three values: kind, namespace, and name. We can display these values or call an API using them.
+
+Since we are linking to pages of the same package, we are using a route ref directly. However, in the following sections, you will see how to link to pages of different plugins.
+
+## External Route References
+
+External routes are made for linking to a page of an external plugin.
+For this section example, let's assume that we want to link from the Catalog entities list page to the Scaffolder create component page.
+
+We don't want to reference the Scaffolder plugin directly, since that would create an unnecessary dependency. It would also provide little flexibility in allowing the app to tie plugins together, with the links instead being dictated by the plugins themselves. To solve this, we use an `ExternalRouteRef`. Much like regular route references, they can be passed to `useRouteRef` to create concrete URLs, but they can not be used in page extensions and instead have to be associated with a target route using route bindings in the app.
+
+We create a new `RouteRef` inside the Scaffolder plugin, using a neutral name that describes its role in the plugin rather than a specific plugin page that it might be linking to, allowing the app to decide the final target. If the Catalog entity list page for example wants to link the Scaffolder create component page in the header, it might declare an `ExternalRouteRef` similar to this:
+
+```tsx title="plugins/catalog/src/routes.ts"
+import { createExternalRouteRef } from '@backstage/frontend-plugin-api';
+
+export const createComponentExternalRouteRef = createExternalRouteRef();
+```
+
+External routes are also used in a similar way as regular routes:
+
+```tsx title="plugins/catalog/src/components/IndexPage.tsx"
+import React from 'react';
+import { useRouteRef } from '@backstage/frontend-plugin-api';
+import { createComponentExternalRouteRef } from '../routes';
+
+export const IndexPage = () => {
+ // highlight-next-line
+ const getCreateComponentPath = useRouteRef(createComponentExternalRouteRef);
+ return (
+ Details Page
+-
+ {/* highlight-start */}
+
- Kind: {params.kind} +
- Namespace: {params.namespace} +
- Name: {params.name} + {/* highlight-end */} +
+
+ );
+};
+```
+
+Given the above binding, using `useRouteRef(createComponentExternalRouteRef)` within the Catalog plugin will let us create a link to whatever path the Scaffolder create component page is mounted at. Note that there is no direct dependency between the Catalog plugin and Scaffolder, that is, we are not importing the `createComponentExternalRouteRef` from the Scaffolder package.
+
+Now the only thing left is to provide the page and external route via a plugin:
+
+```tsx title="plugins/catalog/src/plugin.tsx"
+import React from 'react';
+import {
+ createPlugin,
+ createPageExtension,
+ useRouteRef,
+} from '@backstage/frontend-plugin-api';
+import { indexRouteRef, createComponentExternalRouteRef } from './routes';
+
+const catalogIndexPage = createPageExtension({
+ defaultPath: '/entities',
+ routeRef: indexRouteRef,
+ loader: () => import('./components').then(m => Index Page
+ {/* highlight-next-line */} + Create Component +
+
+ );
+};
+```
## Sub Route References
-
-
-```ts
-/*
-
-Some examples
-
-export const indexPageRouteRef = createRouteRef()
-
-export const catalogPlugin = createPlugin({
- id: 'catalog,
- routes: {
- index: indexPageRouteRef,
- },
-})
-
-// in catalog plugin
-
-import {indexPageRouteRef} from '../../routes
-
-const link = useRouteRef(indexPageRouteRef)
-
-// scaffolder
-
-export const catalogIndexPageRouteRef = createExternalRouteRef({
- defaultTarget: 'catalog/index',
-})
-
-export const scaffolderPlugin = createPlugin({
- id: 'scaffolder,
- externalRoutes: {
- catalogIndex: catalogIndexPageRouteRef,
- },
-})
-
-
-import {catalogIndexPageRouteRef} from '../../routes
-
-const link = useRouteRef(catalogIndexPageRouteRef)
-
-// app
-
-import {catalogPlugin} from '@backstage/plugin-catalog'
-
-const app = createApp({
- bindRoutes({bind}) {
- bind(scaffolderPlugin, {
- catalogIndex: catalogPlugin.routes.index,
- })
- },
-})
-*/
+export const indexRouteRef = createRouteRef();
+// highlight-start
+export const detailsSubRouteRef = createSubRouteRef({
+ parent: indexRouteRef,
+ path: '/details',
+});
+// highlight-end
+```
+
+There are substantial differences between creating subroutes and regular or external routes because subroutes are associated with regular routes, and the sub route path must be specified. The path string must include the parameters if this sub route has them:
+
+```tsx title ="plugins/catalog/src/routes.ts"
+// Omitting rest of the previous example file
+export const detailsSubRouteRef = createSubRouteRef({
+ parent: indexRouteRef,
+ // highlight-next-line
+ path: '/:name/:namespace/:kind',
+});
+```
+
+Using subroutes in a page extension is as simple as this:
+
+```tsx title="plugins/catalog/src/components/IndexPage.ts"
+import React from 'react';
+import { Routes, Route, useLocation } from 'react-router-dom';
+import { useRouteRef } from '@backstage/frontend-plugin-api';
+import { indexRouteRef, detailsSubRouteRef } from '../routes';
+import { DetailsPage } from './DetailsPage';
+
+export const IndexPage = () => {
+ const { pathname } = useLocation();
+ const getIndexPath = useRouteRef(indexRouteRef);
+ const getDetailsPath = useRouteRef(detailsSubRouteRef);
+ return (
+ Index Page
+ {/* Rendering the link only if the getCreateComponentPath is defined */} + {/* highlight-start */} + {getCreateComponentPath && ( + Create Component + )} + {/* highlight-end */} +
+
+
+
+ );
+};
+```
+
+This is how you can get the parameters of a sub route URL:
+
+```tsx title="plugins/catalog/src/components/DetailsPage.ts"
+import React from 'react';
+import { useParams } from 'react-router-dom';
+
+export const DetailsPage = () => {
+ // highlight-next-line
+ const params = useParams();
+ return (
+ Index Page
+ {/* Linking to the details sub route */} + {pathname === getIndexPath() ? ( + // highlight-start + + Show details + + // highlight-end + ) : ( + // highlight-next-line + Hide details + )} + {/* Registering the details sub route */} +
+
+ );
+};
+```
+
+Finally, see how a plugin can provide subroutes:
+
+```tsx title="plugins/catalog/src/plugin.ts"
+import React from 'react';
+import {
+ createPlugin,
+ createPageExtension,
+} from '@backstage/frontend-plugin-api';
+import { indexRouteRef, detailsSubRouteRef } from './routes';
+
+const catalogIndexPage = createPageExtension({
+ defaultPath: '/entities',
+ routeRef: indexRouteRef,
+ loader: () => import('./components').then(m => Details Sub Page
+-
+ {/* highlight-start */}
+
- Kind: {params.kind} +
- Namespace: {params.namespace} +
- Name: {params.name} + {/* highlight-end */} +
+
+ );
+}
+```
+
+```tsx title="in src/plugin.ts - Registering a factory for our API"
+import {
+ createApiFactory,
+ createApiExtension,
+} from '@backstage/frontend-plugin-api';
+import { exampleApiRef, DefaultExampleApi } from './api';
+
+// highlight-add-start
+const exampleApi = createApiExtension({
+ factory: createApiFactory({
+ api: exampleApiRef,
+ deps: {},
+ factory: () => new DefaultExampleApi(),
+ }),
+});
+// highlight-add-end
+
+/* Omitted definitions for examplePage, exampleNavItem, and rootRouteRef. */
+
+export const examplePlugin = createPlugin({
+ id: 'example',
+ extensions: [
+ // highlight-add-next-line
+ exampleApi,
+ examplePage,
+ exampleNavItem,
+ ],
+ routes: {
+ root: rootRouteRef,
+ },
+});
+```
+
+## 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.
+
+```tsx title="in src/plugin.ts - An example entity content extension"
+import { createEntityContentExtension } from '@backstage/plugin-catalog-react';
+
+// Entity content extensions are similar to page extensions in that they are rendered at a route,
+// although they also have a title to support in-line navigation between the different content.
+// Just like a page extension the content is lazy loaded, and you can also provide a
+// route reference if you want to be able to generate a URL that links to the content.
+const exampleEntityContent = createEntityContentExtension({
+ defaultPath: 'example',
+ defaultTitle: 'Example',
+ loader: () =>
+ import('./components/ExampleEntityContent').then(m => (
+ Example Page
+Example: {exampleApi.getExample().example}
+
+
diff --git a/docs/overview/glossary.md b/docs/overview/glossary.md
deleted file mode 100644
index ab7d224f4d..0000000000
--- a/docs/overview/glossary.md
+++ /dev/null
@@ -1,26 +0,0 @@
----
-id: glossary
-title: Backstage Glossary
-# prettier-ignore
-description: List of terms, abbreviations, and phrases used in Backstage, together with their explanations.
----
-
-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.
-
-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 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. |
-| 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. |
diff --git a/docs/overview/logos.md b/docs/overview/logos.md
index ac54640e33..fe993cc378 100644
--- a/docs/overview/logos.md
+++ b/docs/overview/logos.md
@@ -12,31 +12,31 @@ The assets below are all in `.svg` format. Other formats are available in the
## Backstage logo
-
- 
+
+
-
- 
+
+
-
- 
+
+
## Backstage icon
diff --git a/docs/overview/support.md b/docs/overview/support.md
index c968405a99..0433683406 100644
--- a/docs/overview/support.md
+++ b/docs/overview/support.md
@@ -6,12 +6,12 @@ description: Support and Community Details and Links
- [Discord chatroom](https://discord.gg/backstage-687207715902193673) - Get support or discuss the
project.
-- [Stack Overflow](https://stackoverflow.com/questions/tagged/backstage) - Browse or ask questions on Stack Overflow.
- [Good First Issues](https://github.com/backstage/backstage/contribute) - Start
here if you want to contribute.
- [RFCs](https://github.com/backstage/backstage/labels/rfc) - Help shape the
technical direction by reviewing _Request for Comments_ issues.
-- [FAQ](../FAQ.md) - Frequently Asked Questions.
+- [BEPs](https://github.com/backstage/backstage/tree/master/beps#backstage-enhancement-proposals-beps) - A Backstage Enhancement Proposal (BEP) is a way to propose, communicate and coordinate on new efforts for the Backstage project.
+- [FAQ](../faq/index.md) - Frequently Asked Questions.
- [Code of Conduct](https://github.com/backstage/backstage/blob/master/CODE_OF_CONDUCT.md) -
This is how we roll.
- [Blog](https://backstage.io/blog/) - Announcements and updates.
@@ -23,41 +23,3 @@ description: Support and Community Details and Links
## Community Hub
Check out the Backstage.io [Backstage Community Hub](https://backstage.io/community) for the Community Sessions, recordings, and community resources.
-
-### Adding a recording to the meetup page
-
-To add a new recording to the [meetup page](https://backstage.io/on-demand)
-create a file in
-[`microsite/data/on-demand`](https://github.com/backstage/backstage/tree/master/microsite/data/on-demand)
-with your recording's information. Filenames should be in the format `yyyymmdd-xx.yaml`. The page will sort using the filename. Example file content:
-
-```yaml
----
-title: # name of the meetup
-date: February 23, 2022 # date, format: Month day, year.
-category: Meetup # Can be Event, Meetup, Webinar
-description: # description, summary
-youtubeUrl: # Url to youtube video
-youtubeImgUrl: # Url to the preview image, for Youtube this is the format: https://i1.ytimg.com/vi/
+ 
+ 
+ 
+
+
## Benefits
diff --git a/docs/permissions/concepts.md b/docs/permissions/concepts.md
index e7d65b3583..7c8b9e9f69 100644
--- a/docs/permissions/concepts.md
+++ b/docs/permissions/concepts.md
@@ -6,11 +6,11 @@ description: A list of important permission framework concepts
### Permission
-Any action that a user performs within Backstage may be represented as a permission. More complex actions, like executing a software template, may require authorization for multiple permissions throughout the flow. Permissions are identified by a unique name and optionally include a set of attributes that describe the corresponding action. Plugins are responsible for defining and exposing the permissions they enforce.
+Any action that a user performs within Backstage may be represented as a permission. More complex actions, like executing a [software template](../references/glossary.md#software-templates), may require [authorization](../references/glossary.md#authorization) for multiple permissions throughout the flow. Permissions are identified by a unique name and optionally include a set of attributes that describe the corresponding action. [Plugins](../references/glossary.md#plugin) are responsible for defining and exposing the permissions they enforce as well as enforcing restrictions from the permission framework.
### Policy
-User permissions are authorized by a central, user-defined permission policy. At a high level, a policy is a function that receives a Backstage user and permission, and returns a decision to allow or deny. Policies are expressed as code, which decouples the framework from any particular authorization model, like role-based access control (RBAC) or attribute-based access control (ABAC).
+User [permissions](../references/glossary.md#permission-permission-plugin) are authorized by a central, user-defined permission policy. At a high level, a policy is a function that receives a Backstage user and permission, and returns a decision to allow or deny. Policies are expressed as code, which decouples the framework from any particular [authorization](../references/glossary.md#authorization) model, like role-based access control (RBAC) or attribute-based access control (ABAC).
### Policy decision versus enforcement
@@ -18,8 +18,10 @@ Two important responsibilities of any authorization system are to decide if a us
### Resources and rules
-In many cases, a permission represents a user's interaction with another object. This object likely has information that policy authors can use to define more granular access. The permission framework introduces two abstractions to account for this: resources and rules. Resources represent the objects that users interact with. Rules are predicate-based controls that tap into a resource's data. For example, the catalog plugin defines a resource for catalog entities and a rule to check if an entity has a given annotation.
+In many cases, a permission represents a user's interaction with another object. This object likely has information that policy authors can use to define more granular access. The permission framework introduces two abstractions to account for this: [resources](../references/glossary.md#resource-permission-plugin) and [rules](../references/glossary.md#rule-permission-plugin). For example, the catalog plugin defines a resource for catalog entities and a rule to check if an entity has a given annotation.
### Conditional decisions
-Rules need additional data before they can be used in a decision. For example, the catalog plugin's "has annotation" rule needs to know what annotation to look for on a given entity. Once a rule is bound to relevant information it forms a condition. Conditions are then used to return a conditional decision from a policy. Conditional decisions tell the permission framework to delegate evaluation to the plugin that owns the corresponding resource. Permission requests that result in a conditional decision are allowed if all of the provided conditions evaluate to be true. This conditional behavior avoids coupling between policies and resource schemas, and allows plugins to evaluate complex rules in an efficient way. For example, a plugin may convert a conditional decision to a database query instead of loading and filtering objects in memory.
+[Rules](../references/glossary.md#rule-permission-plugin) need additional data before they can be used in a decision. Once a [rule](../references/glossary.md#rule-permission-plugin) is bound to relevant information it forms a [condition](../references/glossary.md#condition-permission-plugin). Conditional decisions tell the [permission framework](#permission) to delegate evaluation to the [plugin](#plugin) that owns the corresponding [resource](#resource-permission-plugin). Permission requests that result in a conditional decision are allowed if all of the provided conditions evaluate to be true.
+
+A good example would be the catalog plugin's "has annotation" rule which needs to know what annotation to look for on a given entity. The permission framework would respond to a request by the catalog plugin in this case with a condition decision. The catalog plugin would then need to correctly filter for entities matching the "has annotations" condition. This conditional behavior avoids coupling between policies and resource schemas, and allows plugins to evaluate complex rules in an efficient way. For example, a plugin may convert a conditional decision to a database query instead of loading and filtering objects in memory.
diff --git a/docs/permissions/custom-rules.md b/docs/permissions/custom-rules.md
index c0f4e3e156..9063ed7257 100644
--- a/docs/permissions/custom-rules.md
+++ b/docs/permissions/custom-rules.md
@@ -4,7 +4,7 @@ title: Defining custom permission rules
description: How to define custom permission rules for existing resources
---
-For some use cases, you may want to define custom [rules](./concepts.md#resources-and-rules) in addition to the ones provided by a plugin. In the [previous section](./writing-a-policy.md) we used the `isEntityOwner` rule to control access for catalog entities. Let's extend this policy with a custom rule that checks what [system](https://backstage.io/docs/features/software-catalog/system-model#system) an entity is part of.
+For some use cases, you may want to define custom [rules](../references/glossary.md#rule-permission-plugin) in addition to the ones provided by a plugin. In the [previous section](./writing-a-policy.md) we used the `isEntityOwner` rule to control access for catalog entities. Let's extend this policy with a custom rule that checks what [system](https://backstage.io/docs/features/software-catalog/system-model#system) an entity is part of.
## Define a custom rule
diff --git a/docs/permissions/getting-started.md b/docs/permissions/getting-started.md
index 01a268f7ef..e241f0e38e 100644
--- a/docs/permissions/getting-started.md
+++ b/docs/permissions/getting-started.md
@@ -48,7 +48,7 @@ The permissions framework uses a new `permission-backend` plugin to accept autho
```bash
# From your Backstage root directory
- yarn add --cwd packages/backend @backstage/plugin-permission-backend
+ yarn --cwd packages/backend add @backstage/plugin-permission-backend
```
2. Add the following to a new file, `packages/backend/src/plugins/permission.ts`. This adds the permission-backend router, and configures it with a policy which allows everything.
diff --git a/docs/permissions/overview.md b/docs/permissions/overview.md
index 693f848c82..8630b85e23 100644
--- a/docs/permissions/overview.md
+++ b/docs/permissions/overview.md
@@ -22,7 +22,7 @@ The permission framework was designed with a few key properties in mind:
- **Integrators** can author or configure policies that define which users can take certain actions upon which resources.
-
+
1. The user triggers a request to perform some action. The request specifies the authorization details using the permission specified by the plugin (in this case, a resource read action).
diff --git a/docs/permissions/plugin-authors/01-setup.md b/docs/permissions/plugin-authors/01-setup.md
index 8134fc0c39..a674d82e25 100644
--- a/docs/permissions/plugin-authors/01-setup.md
+++ b/docs/permissions/plugin-authors/01-setup.md
@@ -41,8 +41,8 @@ The source code is available here:
```sh
# From your Backstage root directory
- yarn add --cwd packages/backend @internal/plugin-todo-list-backend @internal/plugin-todo-list-common
- yarn add --cwd packages/app @internal/plugin-todo-list
+ yarn --cwd packages/backend add @internal/plugin-todo-list-backend @internal/plugin-todo-list-common
+ yarn --cwd packages/app add @internal/plugin-todo-list
```
3. Include the backend and frontend plugin in your application:
diff --git a/docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md b/docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md
index 23bc4e84f1..f3380bdb6f 100644
--- a/docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md
+++ b/docs/permissions/plugin-authors/02-adding-a-basic-permission-check.md
@@ -4,9 +4,9 @@ title: 2. Adding a basic permission check
description: Explains how to add a basic permission check to a Backstage plugin
---
-If the outcome of a permission check doesn't need to change for different [resources](../concepts.md#resources-and-rules), you can use a _basic permission check_. For this kind of check, we simply need to define a [permission](../concepts.md#resources-and-rules), and call `authorize` with it.
+If the outcome of a permission check doesn't need to change for different [resources](../../references/glossary.md#resource-permission-plugin), you can use a _basic permission check_. For this kind of check, we simply need to define a permission, and call `authorize` with it.
-For this tutorial, we'll use a basic permission check to authorize the `create` endpoint in our todo-backend. This will allow Backstage integrators to control whether each of their users is authorized to create todos by adjusting their [permission policy](../concepts.md#policy).
+For this tutorial, we'll use a basic permission check to authorize the `create` endpoint in our todo-backend. This will allow Backstage integrators to control whether each of their users is authorized to create todos by adjusting their [permission policy](../../references/glossary.md#policy-permission-plugin).
We'll start by creating a new permission, and then we'll use the permission api to call `authorize` with it during todo creation.
diff --git a/docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md b/docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md
index a4d51b64d0..76c1a85e24 100644
--- a/docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md
+++ b/docs/permissions/plugin-authors/03-adding-a-resource-permission-check.md
@@ -4,7 +4,7 @@ title: 3. Adding a resource permission check
description: Explains how to add a resource permission check to a Backstage plugin
---
-When performing updates (or other operations) on specific [resources](../concepts.md#resources-and-rules), the permissions framework allows for the decision to be based on characteristics of the resource itself. This means that it's possible to write policies that (for example) allow the operation for users that own a resource, and deny the operation otherwise.
+When performing updates (or other operations) on specific [resources](../../references/glossary.md#resource-permission-plugin), the permissions framework allows for the decision to be based on characteristics of the resource itself. This means that it's possible to write policies that (for example) allow the operation for users that own a resource, and deny the operation otherwise.
## Creating the update permission
diff --git a/docs/plugins/backend-plugin.md b/docs/plugins/backend-plugin.md
index d2e93bb08c..22d4bae371 100644
--- a/docs/plugins/backend-plugin.md
+++ b/docs/plugins/backend-plugin.md
@@ -69,7 +69,7 @@ to your backend.
```bash
# From your Backstage root directory
-yarn add --cwd packages/backend @internal/plugin-carmen-backend@^0.1.0 # Change this to match the plugin's package.json
+yarn --cwd packages/backend add @internal/plugin-carmen-backend@^0.1.0 # Change this to match the plugin's package.json
```
Create a new file named `packages/backend/src/plugins/carmen.ts`, and add the
diff --git a/docs/plugins/new-backend-system.md b/docs/plugins/new-backend-system.md
index 0fc44f283f..08ed7e73c7 100644
--- a/docs/plugins/new-backend-system.md
+++ b/docs/plugins/new-backend-system.md
@@ -26,7 +26,7 @@ const backend = createBackend();
backend.add(import('@backstage/plugin-catalog-backend'));
// Start up the backend
-await backend.start();
+backend.start();
```
One notable change that helped achieve this much slimmer backend setup is the introduction of a system for dependency injection, which is very similar to the one in the Backstage frontend.
diff --git a/docs/plugins/plugin-development.md b/docs/plugins/plugin-development.md
index 8d8db8c387..5ba1de4a7d 100644
--- a/docs/plugins/plugin-development.md
+++ b/docs/plugins/plugin-development.md
@@ -40,7 +40,7 @@ import { createRouteRef } from '@backstage/core-plugin-api';
// Note: This route ref is for internal use only, don't export it from the plugin
export const rootRouteRef = createRouteRef({
- title: 'Example Page',
+ id: 'Example Page',
});
```
diff --git a/docs/publishing.md b/docs/publishing.md
index 15813275de..29853955f1 100644
--- a/docs/publishing.md
+++ b/docs/publishing.md
@@ -140,4 +140,26 @@ process is used to release an emergency fix as version `6.5.1` in the patch rele
### When the release workflow is not triggered for some reason, such as a GitHub incident
-Ask one of the maintainers to force push master back to a previous commit and then push the release merge commit again.
+Ask one of the maintainers to trigger [the Deploy packages](https://github.com/backstage/backstage/actions/workflows/deploy_packages.yml) workflow with the "Unconditionally trigger the release job to run" checkbox set, on the `master` branch. Please validate first that nothing substantial has been pushed to master since the original failed release attempt! For this reason, it is wise to have the master branch locked until each release has gone through.
+
+### The release successfully published packages but failed when finalizing the release
+
+If it's an intermittent failure then it is safe to re-trigger the release workflow again.
+
+If re-triggering doesn't or won't help, the following steps can be taken to complete the release:
+
+- Manually create a git tag for the release if it doesn't already exist
+- Manually create a [new GitHub release](https://github.com/backstage/backstage/releases/new).
+- Trigger the repository dispatch workflow using the following request, replace `+Replace: `"@testing-library/react": "^14.0.0"` + +Find: `"@testing-library/react-hooks": ".*",?`
+Replace: `
Copyright © 2023 Backstage Project Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage
', + 'Copyright © 2024 Backstage Project Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage
', }, algolia: { apiKey: '1f0ba86672ccfc3576faa94583e5b318', diff --git a/microsite/lighthouserc.js b/microsite/lighthouserc.js new file mode 100644 index 0000000000..f0024ee0b3 --- /dev/null +++ b/microsite/lighthouserc.js @@ -0,0 +1,68 @@ +/* + * Copyright 2023 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +var sidebars = require('./sidebars.json'); + +module.exports = { + ci: { + collect: { + url: [ + /** Home */ + 'http://localhost:3000', + /** Docs - Getting Started */ + 'http://localhost:3000/docs/getting-started', + /** Docs - Software Catalog */ + 'http://localhost:3000/docs/features/software-catalog', + /** Docs - Create a Plugin */ + 'http://localhost:3000/docs/plugins/create-a-plugin', + /** Docs - Designing for Backstage */ + 'http://localhost:3000/docs/dls/design', + /** Blog */ + 'http://localhost:3000/blog', + /** Plugins */ + 'http://localhost:3000/plugins', + /** Demos */ + 'http://localhost:3000/demos', + /** Community */ + 'http://localhost:3000/community', + /** Releases */ + ...sidebars.releases['Release Notes'].map( + path => `http://localhost:3000/docs/${path}`, + ), + ], + settings: { + onlyCategories: ['accessibility'], + output: ['html', 'json'], + outputPath: './.lighthouseci/reports', + preset: 'desktop', + }, + // refers to root package scripts + startServerCommand: 'yarn run start:microsite', + startServerReadyPattern: 'compiled successfully', + startServerReadyTimeout: 600000, + numberOfRuns: 1, + }, + assert: { + assertions: { + 'categories:performance': 'off', + 'categories:pwa': 'off', + 'categories:best-practices': 'off', + 'categories:seo': 'off', + 'categories:accessibility': ['error', { minScore: 0.95 }], + }, + }, + }, +}; diff --git a/microsite/package.json b/microsite/package.json index 53309fb358..dadc06518d 100644 --- a/microsite/package.json +++ b/microsite/package.json @@ -18,21 +18,21 @@ "docusaurus": "docusaurus" }, "devDependencies": { - "@docusaurus/module-type-aliases": "0.0.0-5703", + "@docusaurus/module-type-aliases": "^3.1.1", "@spotify/prettier-config": "^14.0.0", "@tsconfig/docusaurus": "^2.0.0", "@types/luxon": "^3.0.0", "@types/webpack-env": "^1.18.0", "js-yaml": "^4.1.0", "prettier": "^2.6.2", - "typescript": "~5.0.0", + "typescript": "~5.1.0", "yaml-loader": "^0.8.0" }, "prettier": "@spotify/prettier-config", "dependencies": { - "@docusaurus/core": "0.0.0-5703", - "@docusaurus/plugin-client-redirects": "0.0.0-5703", - "@docusaurus/preset-classic": "0.0.0-5703", + "@docusaurus/core": "^3.1.1", + "@docusaurus/plugin-client-redirects": "^3.1.1", + "@docusaurus/preset-classic": "^3.1.1", "@swc/core": "^1.3.46", "clsx": "^2.0.0", "docusaurus-plugin-sass": "^0.2.3", diff --git a/microsite/sidebars.json b/microsite/sidebars.json index c54e59f45c..146d8db059 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -37,7 +37,6 @@ "overview/versioning-policy", "overview/threat-model", "overview/support", - "overview/glossary", "overview/logos" ], "Getting Started": [ @@ -309,7 +308,8 @@ "auth/google/gcp-iap-auth", "auth/okta/provider", "auth/oauth2-proxy/provider", - "auth/onelogin/provider" + "auth/onelogin/provider", + "auth/vmware-cloud/provider" ] }, "auth/identity-resolver", @@ -318,8 +318,7 @@ "auth/add-auth-provider", "auth/service-to-service-auth", "auth/autologout", - "auth/troubleshooting", - "auth/glossary" + "auth/troubleshooting" ], "Permissions": [ "permissions/overview", @@ -411,7 +410,20 @@ { "type": "category", "label": "Building Plugins", - "items": ["frontend-system/building-plugins/testing"] + "items": [ + "frontend-system/building-plugins/index", + "frontend-system/building-plugins/testing", + "frontend-system/building-plugins/extension-types", + "frontend-system/building-plugins/built-in-data-refs" + ] + }, + { + "type": "category", + "label": "Building Apps", + "items": [ + "frontend-system/building-apps/index", + "frontend-system/building-apps/built-in-extensions" + ] }, { "type": "category", @@ -448,6 +460,7 @@ "tutorials/journey", "tutorials/quickstart-app-plugin", "tutorials/react-router-stable-migration", + "tutorials/react18-migration", "tutorials/package-role-migration", "tutorials/migrating-away-from-core", "tutorials/configuring-plugin-databases", @@ -473,7 +486,8 @@ "architecture-decisions/adrs-adr012", "architecture-decisions/adrs-adr013" ], - "FAQ": ["FAQ"], - "Accessibility": ["accessibility/index"] + "FAQ": ["faq/index", "faq/product", "faq/technical"], + "Accessibility": ["accessibility/index"], + "References": ["references/glossary"] } } diff --git a/microsite/src/pages/community/index.tsx b/microsite/src/pages/community/index.tsx index 9b10183ea4..42c42ae0c3 100644 --- a/microsite/src/pages/community/index.tsx +++ b/microsite/src/pages/community/index.tsx @@ -36,19 +36,14 @@ const Community = () => { label: 'Community newsletter', link: 'https://info.backstage.spotify.com/newsletter_subscribe', }, - { - content: 'Join the', - label: 'Twitter community', - link: 'https://twitter.com/i/communities/1494019781716062215', - }, ]; const officialInitiatives: ICollectionItem[] = [ { title: 'Community sessions', content: - 'Maintainers and adopters meet monthly to share updates, demos, and ideas. Yep, all sessions are recorded!', - link: '/on-demand', + 'Maintainers and adopters meet monthly to share updates, demos, and ideas. You can find recorded session on our YouTube channel!', + link: 'https://github.com/backstage/community/tree/main/backstage-community-sessions#backstage-community-sessions', label: 'Join a session', }, { @@ -58,45 +53,11 @@ const Community = () => { link: 'https://info.backstage.spotify.com/newsletter_subscribe', label: 'Subscribe', }, - { - title: 'Contributor Spotlight', - content: - "A recognition for valuable community work. Nominate contributing members for their efforts! We'll put them in the spotlight ❤️", - link: '/nominate', - label: 'Nominate now', - }, - ]; - - const communityInitiatives: ICollectionItem[] = [ - { - title: 'Open Mic Meetup', - content: ( - <> - A casual get together of Backstage users sharing their experiences and - helping each other. Hosted by{' '} - Roadie.io and{' '} - Frontside Software. - - ), - link: 'https://backstage-openmic.com/', - label: 'Learn more', - }, - { - title: 'Backstage Weekly Newsletter', - content: ( - <> - A weekly newsletter with news, updates and things community from your - friends at Roadie.io. - - ), - link: 'https://roadie.io/backstage-weekly/', - label: 'Learn more', - }, ]; const trainingNCertifications: ICollectionItem[] = [ { - title: 'Open Mic Meetup', + title: 'Introduction to Backstage: Developer Portals Made Easy (LFS142x)', content: 'This is a course produced and curated by the Linux Foundation. This course introduces you to Backstage and how to get started with the project.', link: 'https://training.linuxfoundation.org/training/introduction-to-backstage-developer-portals-made-easy-lfs142x/', @@ -127,8 +88,8 @@ const Community = () => { }, { name: 'VMWare', - url: 'https://www.vmware.com', - logo: 'img/partner-logo-vmware.png', + url: 'https://tanzu.vmware.com/', + logo: 'img/partner-logo-tanzubybroadcom.png', }, ]; //#endregion @@ -204,30 +165,6 @@ const Community = () => { -{content}
-
-
- Contributor Spotlight nomination}>
-
-
-
-
- {title}
- -on {date}
- - {category} - -
-
- }
- body={{description}
} - footer={ - category.toLowerCase() === 'upcoming' ? ( - <> - - Event page - - - - Remind me - - - ) : ( - - Watch on YouTube - - ) - } - /> -); diff --git a/microsite/src/pages/on-demand/index.tsx b/microsite/src/pages/on-demand/index.tsx deleted file mode 100644 index 8d78c393ce..0000000000 --- a/microsite/src/pages/on-demand/index.tsx +++ /dev/null @@ -1,78 +0,0 @@ -import Layout from '@theme/Layout'; -import clsx from 'clsx'; -import React from 'react'; - -import { IOnDemandData, OnDemandCard } from './_onDemandCard'; -import pluginsStyles from './onDemand.module.scss'; -import { truncateDescription } from '@site/src/util/truncateDescription'; -import Link from '@docusaurus/Link'; - -//#region Plugin data import -const onDemandContext = require.context( - '../../../data/on-demand', - false, - /\.ya?ml/, -); - -const onDemandData = onDemandContext.keys().reduce( - (acum, id) => { - const pluginData: IOnDemandData = onDemandContext(id).default; - - acum[ - pluginData.category === 'Upcoming' ? 'upcomingEvents' : 'onDemandEvents' - ].push(truncateDescription(pluginData)); - - return acum; - }, - { - upcomingEvents: [] as IOnDemandData[], - onDemandEvents: [] as IOnDemandData[], - }, -); -//#endregion - -const Plugins = () => ( -
-
-
-
-
-
-
-
-
-
-
- Add an event or recording
-
- Community sessions
- -- Upcoming events and recorded sessions about updates, demos and - discussions. -
-Upcoming live events
- -
- {onDemandData.upcomingEvents.map(eventData => (
-
-
- Community on demand
- -
- {onDemandData.onDemandEvents.map(eventData => (
-
-