Merge branch 'master' into mobile-sidebar

docs/architecture-decisions/adr011-plugin-package-structure.md

@@ -35,9 +35,11 @@ We follow this structure for plugin packages (where `x` is the plugin name, for
 example `catalog` or `techdocs`):
 
 - `x`: Contains the main frontend code of the plugin.
+- `x-module-<name>`: Contains optional modules related to the frontend plugin
+  package.
 - `x-backend`: Contains the main backend code of the plugin.
 - `x-backend-module-<name>`: Contains optional modules related to the backend
-  plugin.
+  plugin package.
 - `x-react`: Contains shared widgets, hooks and similar that both the plugin
   itself (`x`) and third-party frontend plugins can depend on.
 - `x-node`: Contains utilities for backends that both the plugin backend itself

docs/assets/architecture-overview/package-architecture.drawio

@@ -0,0 +1 @@
+<mxfile host="Chrome" modified="2021-12-30T23:10:43.723Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36" etag="XmQE_awyVPeS9B3bWnM_" version="15.5.6" type="device"><diagram id="M4OCM2KiCGRnt6vHj1W_" name="Page-1">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</diagram></mxfile>

docs/features/software-catalog/catalog-customization.md

@@ -30,12 +30,15 @@ export const CustomCatalogPage = ({
   actions,
   initiallySelectedFilter = 'owned',
 }: CatalogPageProps) => {
+  const createComponentLink = useRouteRef(
+    catalogPlugin.externalRoutes.createComponent,
+  );
   return (
     <PageWithHeader title={`${orgName} Catalog`} themeId="home">
       <EntityListProvider>
         <Content>
           <ContentHeader titleComponent={<CatalogKindHeader />}>
-            <CreateButton title="Create Component" to={link} />
+            <CreateButton title="Create Component" to={createComponentLink()} />
             <SupportButton>All your software catalog entities</SupportButton>
           </ContentHeader>
           <FilteredEntityLayout>

docs/getting-started/keeping-backstage-updated.md

@@ -22,6 +22,13 @@ yarn backstage-cli versions:bump
 The reason for bumping all `@backstage` packages at once is to maintain the
 dependencies that they have between each other.
 
+If you are using other plugins you can pass in the `--pattern` option to update
+more than just the `@backstage/*` dependencies.
+
+```bash
+yarn backstage-cli versions:bump --pattern '@{backstage,roadiehq}/*'
+```
+
 ## Following create-app template changes
 
 The `@backstage/create-app` command creates the initial structure of your

docs/integrations/aws-s3/locations.md

@@ -20,8 +20,7 @@ To use this integration, add configuration to your `app-config.yaml`:
 ```yaml
 integrations:
   awsS3:
-    - host: amazonaws.com
-      accessKeyId: ${AWS_ACCESS_KEY_ID}
+    - accessKeyId: ${AWS_ACCESS_KEY_ID}
       secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
 ```
 
@@ -35,8 +34,21 @@ instruct the AWS S3 reader to assume a role before accessing S3:
 ```yaml
 integrations:
   awsS3:
-    - host: amazonaws.com
-      accessKeyId: ${AWS_ACCESS_KEY_ID}
+    - accessKeyId: ${AWS_ACCESS_KEY_ID}
       secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
       roleArn: 'arn:aws:iam::xxxxxxxxxxxx:role/example-role'
 ```
+
+Configuration allows specifying custom S3 endpoint, along with
+[path-style access](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html)
+to support integration with providers like
+[LocalStack](https://github.com/localstack/localstack):
+
+```yaml
+integrations:
+  awsS3:
+    - endpoint: 'http://localhost:4566'
+      s3ForcePathStyle: true
+      accessKeyId: ${AWS_ACCESS_KEY_ID}
+      secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
+```

docs/local-dev/cli-commands.md

@@ -594,6 +594,7 @@ Usage: backstage-cli versions:bump [options]
 
 Options:
   -h, --help  display help for command
+  -p, --pattern Override glob for matching packages to upgrade
 ```
 
 ## versions:check

docs/overview/architecture-overview.md

@@ -164,12 +164,110 @@ https://circleci.com.
 
 ![CircleCI plugin talking to proxy talking to SaaS Circle CI](../assets/architecture-overview/circle-ci-plugin-architecture.png)
 
+## Package Architecture
+
+Backstage relies heavily on NPM packages, both for distribution of libraries,
+and structuring of code within projects. While the way you structure your
+Backstage project is up to you, there is a set of established patterns that we
+encourage you to follow. These patterns can help set up a sound project
+structure as well as provide familiarity between different Backstage projects.
+
+The following diagram shows an overview of the package architecture of
+Backstage. It takes the point of view of an individual plugin and all of the
+packages that it may contain, indicated by the thicker border and italic text.
+Surrounding the plugin are different package groups which are the different
+possible interface points of the plugin. Note that not all library package lists
+are complete as packages have been omitted for brevity.
+
+![Package architecture](../assets/architecture-overview/package-architecture.png)
+
+<!--
+ NOTE: The diagram is exported from /docs/assets/architecture-overview/package-architecture.drawio
+       It can be edited using https://www.diagrams.net/
+       Export it as a PNG with 10px margin without transparent background
+-->
+
+### Overview
+
+The arrows in the diagram above indicate a runtime dependency on the code of the
+target package. This strict dependency graph only applies to runtime
+`dependencies`, and there may be `devDependencies` that break the rules of this
+table for the purpose of testing. While there are some arrows that show a
+dependency on a collection of frontend, backend and isomorphic packages, those
+still have to abide by important compatibility rules shown in the bottom left.
+
+The `app` and `backend` packages are the entry points of a Backstage project.
+The `app` package is the frontend application that brings together a collection
+of frontend plugins and customizes them to fit an organization, while the
+`backend` package is the backend service that powers the Backstage application.
+Worth noting is that there can be more than one instance of each of these
+packages within a project. Particularly the `backend` packages can benefit from
+being split up into smaller deployment units that each serve their own purpose
+with a smaller collection of plugins.
+
+### Plugin Packages
+
+A typical plugin consists of up to five packages, two frontend ones, two
+backend, and one isomorphic packages. All packages within the plugin must share
+a common prefix, typically of the form `@<scope>/plugin-<plugin-id>`, but
+alternatives like `backstage-plugin-<plugin-id>` or
+`@scope/backstage-plugin-<plugin-id>` are also valid. Along with this prefix,
+each of the packages have their own unique suffix that denotes their role. In
+addition to these five plugin packages it's also possible for to a plugin to
+have additional frontend and backend modules that can be installed to enable
+optional features. For a full list of suffixes and their roles, see the
+[Plugin Package Structure ADR](../architecture-decisions/adr011-plugin-package-structure.md).
+
+The `-react`, `-common`, and `-node` plugin packages together form the external
+library of a plugin. The plugin library enables other plugins to build on top of
+and extend a plugin, and likewise allows the plugin to depend on and extend
+other plugins. Because of this, it is preferable that plugin library packages
+allow duplicate installations of themselves, as you may end up with a mix of
+versions being installed as dependencies of various plugins. It is also
+forbidden for plugins to directly import non-library packages from other
+plugins, all communication between plugins must be handled through libraries and
+the application itself.
+
+### Frontend Packages
+
+The frontend packages are grouped into two main groups. The first one is
+"Frontend App Core", which is the set of packages that are only used by the
+`app` package itself. These packages help build up the core structure of the app
+as well as provide a foundation for the plugin libraries to rely upon.
+
+The second group is the rest of the shared packages, further divided into
+"Frontend Plugin Core" and "Frontend Libraries". The core packages that are
+considered particularly stable and form the core of the frontend framework.
+Their most important role is to form the boundary around each plugin and provide
+a set of tools that helps you combine a collection of plugins into a running
+application. The rest of the frontend packages are more traditional libraries
+that serve as building blocks to create plugins.
+
+### Backend Packages
+
+The backend library packages do not currently share a similar plugin
+architecture as the frontend packages. They are instead simply a collection of
+building blocks and patterns that help you build backend services. This is
+however likely to change in the future.
+
+### Common Packages
+
+The common packages are the packages are effectively depended on by all other
+pages. This is a much smaller set of packages but they are also very pervasive.
+Because the common packages are isomorphic and must execute both in the frontend
+and backend, they are never allowed to depend on any of the frontend of backend
+packages.
+
+The Backstage CLI is in a category of its own and is depended on by virtually
+all other packages. It's not a library in itself though, and must always be a
+development dependency only.
+
 ## Databases
 
 As we have seen, both the `lighthouse-audit-service` and `catalog-backend`
 require a database to work with.
 
-The Backstage backend and its builtin plugins are based on the
+The Backstage backend and its built-in plugins are based on the
 [Knex](http://knexjs.org/) library, and set up a separate logical database per
 plugin. This gives great isolation and lets them perform migrations and evolve
 separate from each other.
@@ -184,7 +282,7 @@ yet.
 
 ## Cache
 
-The Backstage backend and its builtin plugins are also able to leverage cache
+The Backstage backend and its built-in plugins are also able to leverage cache
 stores as a means of improving performance or reliability. Similar to how
 databases are supported, plugins receive logically separated cache connections,
 which are powered by [Keyv](https://github.com/lukechilds/keyv) under the hood.

docs/tutorials/quickstart-app-plugin.md

@@ -135,7 +135,7 @@ changes, let's start by wiping this component clean.
 
 ```tsx
 import React from 'react';
-import { useAsync } from 'react-use';
+import useAsync from 'react-use/lib/useAsync';
 import Alert from '@material-ui/lab/Alert';
 import { Table, TableColumn, Progress } from '@backstage/core-components';
 import { githubAuthApiRef, useApi } from '@backstage/core-plugin-api';