From 95d052f829ae31d0907a15a57204eb33fc5b49c6 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 1 Feb 2023 13:16:26 +0100 Subject: [PATCH] docs: make backend-system docs available with disclaimer Signed-off-by: Patrik Oldsberg --- docs/backend-system/architecture/01-index.md | 2 + .../architecture/02-backends.md | 2 + .../architecture/03-services.md | 2 + .../backend-system/architecture/04-plugins.md | 2 + .../architecture/05-extension-points.md | 2 + .../backend-system/architecture/06-modules.md | 2 + .../architecture/07-naming-patterns.md | 2 + .../building-backends/01-index.md | 2 + .../building-backends/08-migrating.md | 2 + .../building-plugins-and-modules/01-index.md | 2 + .../02-testing.md | 2 + .../08-migrating.md | 2 + docs/backend-system/core-services/01-index.md | 2 + microsite/sidebars.json | 68 +++++++++---------- 14 files changed, 58 insertions(+), 36 deletions(-) diff --git a/docs/backend-system/architecture/01-index.md b/docs/backend-system/architecture/01-index.md index 88ba3262df..a9f08c7907 100644 --- a/docs/backend-system/architecture/01-index.md +++ b/docs/backend-system/architecture/01-index.md @@ -6,6 +6,8 @@ sidebar_label: System Architecture description: The structure and architecture of the new Backend System and its component parts --- +> **DISCLAIMER: The new backend system is under active development and is not considered stable** + ## Building Blocks This section introduces the high-level building blocks upon which this new diff --git a/docs/backend-system/architecture/02-backends.md b/docs/backend-system/architecture/02-backends.md index 69b74e7dd3..53670aba12 100644 --- a/docs/backend-system/architecture/02-backends.md +++ b/docs/backend-system/architecture/02-backends.md @@ -6,6 +6,8 @@ sidebar_label: Backend description: Backend instances --- +> **DISCLAIMER: The new backend system is under active development and is not considered stable** + ## The Backend Instance This is the main entry point for creating a backend. It does not have any functionality in and of itself, but is simply responsible for wiring things together. diff --git a/docs/backend-system/architecture/03-services.md b/docs/backend-system/architecture/03-services.md index 96b82d7e95..d202c21740 100644 --- a/docs/backend-system/architecture/03-services.md +++ b/docs/backend-system/architecture/03-services.md @@ -6,6 +6,8 @@ sidebar_label: Services description: Services for backend plugins --- +> **DISCLAIMER: The new backend system is under active development and is not considered stable** + Backend services provide shared functionality available to all backend plugins and modules. They are made available through service references that embed a type that represents the service interface, similar to how [Utility APIs](../../api/utility-apis.md) work in the Backstage frontend system. To use a service in your plugin or module you request an implementation of that service using the service reference. The system surrounding services exists to provide a level of indirection between the service interfaces and their implementation. It is an implementation of dependency injection, where each backend instance is the dependency injection container. The implementation for each service is provided by a service factory, which encapsulates the logic for how each service instance is created. diff --git a/docs/backend-system/architecture/04-plugins.md b/docs/backend-system/architecture/04-plugins.md index f535268b2a..7721b1c9f7 100644 --- a/docs/backend-system/architecture/04-plugins.md +++ b/docs/backend-system/architecture/04-plugins.md @@ -6,6 +6,8 @@ sidebar_label: Plugins description: Backend plugins --- +> **DISCLAIMER: The new backend system is under active development and is not considered stable** + Plugins provide the actual base features of a Backstage backend. Each plugin operates completely independently of all other plugins and they only communicate with each other through network calls. This means that there is a strong degree of isolation between plugins, and that each plugin can be considered a separate microservice. While a default Backstage project has all plugins installed within a single backend, it is also possible to split this setup into multiple backends, with each backend housing one or more plugins. ## Defining a Plugin diff --git a/docs/backend-system/architecture/05-extension-points.md b/docs/backend-system/architecture/05-extension-points.md index f82fde3561..d16a773c0c 100644 --- a/docs/backend-system/architecture/05-extension-points.md +++ b/docs/backend-system/architecture/05-extension-points.md @@ -6,6 +6,8 @@ sidebar_label: Extension Points description: Extension points of backend plugins --- +> **DISCLAIMER: The new backend system is under active development and is not considered stable** + While plugins are able to accept options for lightweight forms of customization and extension, you quickly hit a limit where you need something more powerful to allow users to extend your plugin. For this purpose, the backend system provides a mechanism for plugins to provide extension points, which can be used to expose deeper customizations for your plugin. Extension points are used by modules, which are installed in the backend adjacent to plugins. Modules are covered more in-depth in the [next section](./06-modules.md). Extension points are quite similar to services, in that they both encapsulate an interface in a reference object. The key difference is that extension points are registered and provided by plugins themselves, and do not have any factory associated with them. Extension points for a given plugin are also only accessible to modules that extend that same plugin. diff --git a/docs/backend-system/architecture/06-modules.md b/docs/backend-system/architecture/06-modules.md index 83428c7a26..2f359eaa75 100644 --- a/docs/backend-system/architecture/06-modules.md +++ b/docs/backend-system/architecture/06-modules.md @@ -6,6 +6,8 @@ sidebar_label: Modules description: Modules for backend plugins --- +> **DISCLAIMER: The new backend system is under active development and is not considered stable** + Backend modules are used to extend [plugins](./04-plugins.md) with additional features or change existing behavior. They must always be installed in the same backend instance as the plugin that they extend, and may only extend a single plugin. Modules interact with their target plugin using the [extension points](./05-extension-points.md) registered by the plugin, while also being able to depend on the [services](./03-services.md) of that plugin. Both modules and plugins register an `init` method that is called during startup. In order to ensure that modules have registered all their extensions before the plugin starts up, all modules for each plugin are completely initialized before the plugin itself is initialized. In practice this means that all promises returned by each `init` method of the modules need to resolve before the plugin `init` method is called. This also means that it is not possible to further interact with the extension points once the `init` method has resolved. diff --git a/docs/backend-system/architecture/07-naming-patterns.md b/docs/backend-system/architecture/07-naming-patterns.md index 6bd7c412c3..dc781a61ac 100644 --- a/docs/backend-system/architecture/07-naming-patterns.md +++ b/docs/backend-system/architecture/07-naming-patterns.md @@ -6,6 +6,8 @@ sidebar_label: Naming Patterns description: Naming patterns in the backend system --- +> **DISCLAIMER: The new backend system is under active development and is not considered stable** + These are the naming patterns to adhere to within the backend system. They help us keep exports consistent across packages and make it easier to understand the usage and intent of exports. ### Plugins diff --git a/docs/backend-system/building-backends/01-index.md b/docs/backend-system/building-backends/01-index.md index f810417ed7..de01c6d39c 100644 --- a/docs/backend-system/building-backends/01-index.md +++ b/docs/backend-system/building-backends/01-index.md @@ -6,6 +6,8 @@ sidebar_label: Overview description: Building backends using the new backend system --- +> **DISCLAIMER: The new backend system is under active development and is not considered stable** + > NOTE: If you have an existing backend that is not yet using the new backend > system, see [migrating](./08-migrating.md). diff --git a/docs/backend-system/building-backends/08-migrating.md b/docs/backend-system/building-backends/08-migrating.md index 6e0b84b10f..e503d627ef 100644 --- a/docs/backend-system/building-backends/08-migrating.md +++ b/docs/backend-system/building-backends/08-migrating.md @@ -6,6 +6,8 @@ sidebar_label: Migration Guide description: How to migrate existing backends to the new backend system --- +> **DISCLAIMER: The new backend system is under active development and is not considered stable** + ## Overview This section describes how to migrate an existing Backstage backend service 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 01e35036aa..5fefb3ff16 100644 --- a/docs/backend-system/building-plugins-and-modules/01-index.md +++ b/docs/backend-system/building-plugins-and-modules/01-index.md @@ -6,6 +6,8 @@ sidebar_label: Overview description: Building backend plugins and modules using the new backend system --- +> **DISCLAIMER: The new backend system is under active development and is not considered stable** + > NOTE: If you have an existing backend and/or backend plugins that are not yet > using the new backend system, see [migrating](./08-migrating.md). 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 20bef6fec4..37c5698512 100644 --- a/docs/backend-system/building-plugins-and-modules/02-testing.md +++ b/docs/backend-system/building-plugins-and-modules/02-testing.md @@ -6,6 +6,8 @@ sidebar_label: Testing description: Learn how to test your backend plugins and modules --- +> **DISCLAIMER: The new backend system is under active development and is not considered stable** + Utilities for testing backend plugins and modules are available in `@backstage/backend-test-utils`. This section describes those facilities. diff --git a/docs/backend-system/building-plugins-and-modules/08-migrating.md b/docs/backend-system/building-plugins-and-modules/08-migrating.md index ec003a6fec..ec5836a126 100644 --- a/docs/backend-system/building-plugins-and-modules/08-migrating.md +++ b/docs/backend-system/building-plugins-and-modules/08-migrating.md @@ -6,6 +6,8 @@ sidebar_label: Migration Guide description: How to migrate existing backend plugins to the new backend system --- +> **DISCLAIMER: The new backend system is under active development and is not considered stable** + Migrating an existing backend plugin to the new backend system is fairly straightforward. The process is similar across the majority of plugins which just return a `Router` that is then wired up in the `index.ts` file of your backend. The primary thing that we need to do is to make sure that the dependencies that are required by the plugin are available, and then registering the router with the HTTP router service. Let's look at an example of migrating the Kubernetes backend plugin. In the existing (old) system, the kubernetes backend is structured like this: diff --git a/docs/backend-system/core-services/01-index.md b/docs/backend-system/core-services/01-index.md index 4ef9d75bde..b394391480 100644 --- a/docs/backend-system/core-services/01-index.md +++ b/docs/backend-system/core-services/01-index.md @@ -6,6 +6,8 @@ sidebar_label: Core Services description: Core backend service APIs --- +> **DISCLAIMER: The new backend system is under active development and is not considered stable** + The default backend provides several [core services](https://github.com/backstage/backstage/blob/master/packages/backend-plugin-api/src/services/definitions/coreServices.ts) out of the box which includes access to configuration, logging, URL Readers, databases and more. All core services are available through the `coreServices` namespace in the `@backstage/backend-plugin-api` package. diff --git a/microsite/sidebars.json b/microsite/sidebars.json index fcded5ebfb..f051d3c70b 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -365,44 +365,40 @@ ], "FAQ": ["FAQ"], "Experimental Backend System": [ + "backend-system/index", { - "_hidden_": [ - "backend-system/index", - { - "type": "subcategory", - "label": "Architecture", - "ids": [ - "backend-system/architecture/index", - "backend-system/architecture/services", - "backend-system/architecture/plugins", - "backend-system/architecture/extension-points", - "backend-system/architecture/modules", - "backend-system/architecture/naming-patterns" - ] - }, - { - "type": "subcategory", - "label": "Building Backends", - "ids": [ - "backend-system/building-backends/index", - "backend-system/building-backends/migrating" - ] - }, - { - "type": "subcategory", - "label": "Building Plugins & Modules", - "ids": [ - "backend-system/building-plugins-and-modules/index", - "backend-system/building-plugins-and-modules/testing", - "backend-system/building-plugins-and-modules/migrating" - ] - }, - { - "type": "subcategory", - "label": "Core Services", - "ids": ["backend-system/core-services/index"] - } + "type": "subcategory", + "label": "Architecture", + "ids": [ + "backend-system/architecture/index", + "backend-system/architecture/services", + "backend-system/architecture/plugins", + "backend-system/architecture/extension-points", + "backend-system/architecture/modules", + "backend-system/architecture/naming-patterns" ] + }, + { + "type": "subcategory", + "label": "Building Backends", + "ids": [ + "backend-system/building-backends/index", + "backend-system/building-backends/migrating" + ] + }, + { + "type": "subcategory", + "label": "Building Plugins & Modules", + "ids": [ + "backend-system/building-plugins-and-modules/index", + "backend-system/building-plugins-and-modules/testing", + "backend-system/building-plugins-and-modules/migrating" + ] + }, + { + "type": "subcategory", + "label": "Core Services", + "ids": ["backend-system/core-services/index"] } ] }