From a1ae9cc72c57eec3db9ee88708069c9120197bf6 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Fri, 17 May 2024 11:28:17 +0200 Subject: [PATCH] docs: restructure local-dev and rename to tooling Signed-off-by: Patrik Oldsberg --- .changeset/beige-eagles-cheat.md | 5 +++ .../backend-system/architecture/04-plugins.md | 2 +- docs/deployment/docker.md | 2 +- .../keeping-backstage-updated.md | 4 +-- docs/integrations/github/github-apps.md | 2 +- .../02-adding-a-basic-permission-check.md | 2 +- docs/plugins/create-a-plugin.md | 2 +- docs/plugins/testing.md | 2 +- docs/references/glossary.md | 2 +- docs/releases/v1.20.0.md | 2 +- .../cli/01-overview.md} | 12 +++---- .../cli/02-build-system.md} | 8 ++--- .../cli/03-commands.md} | 16 +++++----- docs/{ => tooling}/local-dev/debugging.md | 0 .../local-dev/linking-local-packages.md | 0 docs/tutorials/package-role-migration.md | 8 ++--- microsite/sidebars.json | 32 +++++++++++-------- mkdocs.yml | 14 ++++---- packages/backend-legacy/README.md | 2 +- packages/cli-node/src/roles/types.ts | 2 +- 20 files changed, 66 insertions(+), 53 deletions(-) create mode 100644 .changeset/beige-eagles-cheat.md rename docs/{local-dev/cli-overview.md => tooling/cli/01-overview.md} (82%) rename docs/{local-dev/cli-build-system.md => tooling/cli/02-build-system.md} (99%) rename docs/{local-dev/cli-commands.md => tooling/cli/03-commands.md} (95%) rename docs/{ => tooling}/local-dev/debugging.md (100%) rename docs/{ => tooling}/local-dev/linking-local-packages.md (100%) diff --git a/.changeset/beige-eagles-cheat.md b/.changeset/beige-eagles-cheat.md new file mode 100644 index 0000000000000..5b5081d2ee7cd --- /dev/null +++ b/.changeset/beige-eagles-cheat.md @@ -0,0 +1,5 @@ +--- +'@backstage/cli-node': patch +--- + +Updated doc link. diff --git a/docs/backend-system/architecture/04-plugins.md b/docs/backend-system/architecture/04-plugins.md index 195c32b049b44..af59c2a48ae62 100644 --- a/docs/backend-system/architecture/04-plugins.md +++ b/docs/backend-system/architecture/04-plugins.md @@ -78,4 +78,4 @@ Plugins must always be designed to be horizontally scalable. This means that you ### Isolated -Plugins must never communicate with each other directly through code, they may only communicate over the network. Plugins that wish to expose an external interface for other plugins and modules to use are recommended to do so through a [node-library](../../local-dev/cli-build-system.md#package-roles) package. The library should export an API client service to make calls to your plugin, or similar construct. +Plugins must never communicate with each other directly through code, they may only communicate over the network. Plugins that wish to expose an external interface for other plugins and modules to use are recommended to do so through a [node-library](../../tooling/cli/02-build-system.md#package-roles) package. The library should export an API client service to make calls to your plugin, or similar construct. diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index f16a2ad13ec3c..154f68c7d1dcb 100644 --- a/docs/deployment/docker.md +++ b/docs/deployment/docker.md @@ -101,7 +101,7 @@ CMD ["node", "packages/backend", "--config", "app-config.yaml"] For more details on how the `backend:bundle` command and the `skeleton.tar.gz` file works, see the -[`backend:bundle` command docs](../local-dev/cli-commands.md#backendbundle). +[`backend:bundle` command docs](../tooling/cli/03-commands.md#backendbundle). The `Dockerfile` is located at `packages/backend/Dockerfile`, but needs to be executed with the root of the repo as the build context, in order to get access diff --git a/docs/getting-started/keeping-backstage-updated.md b/docs/getting-started/keeping-backstage-updated.md index e7324f46030fc..1de8874d562ca 100644 --- a/docs/getting-started/keeping-backstage-updated.md +++ b/docs/getting-started/keeping-backstage-updated.md @@ -13,7 +13,7 @@ starting point that's meant to be evolved. The Backstage CLI has a command to bump all `@backstage` packages and dependencies you're using to the latest versions: -[versions:bump](https://backstage.io/docs/local-dev/cli-commands#versionsbump). +[versions:bump](https://backstage.io/docs/tooling/cli/03-commands#versionsbump). ```bash yarn backstage-cli versions:bump @@ -70,7 +70,7 @@ example, depends on global referential equality. This can cause problems in Backstage with API lookup, or config loading. To help resolve these situations, the Backstage CLI has -[versions:check](https://backstage.io/docs/local-dev/cli-commands#versionscheck). This +[versions:check](https://backstage.io/docs/tooling/cli/03-commands#versionscheck). This will validate versions of `@backstage` packages in your app to check for duplicate definitions: diff --git a/docs/integrations/github/github-apps.md b/docs/integrations/github/github-apps.md index 6e3d028e6d171..b5e252be74c1f 100644 --- a/docs/integrations/github/github-apps.md +++ b/docs/integrations/github/github-apps.md @@ -42,7 +42,7 @@ yarn backstage-cli create-github-app ``` You can read more about the -[`backstage-cli create-github-app`](../../local-dev/cli-commands.md#create-github-app) command. +[`backstage-cli create-github-app`](../../tooling/cli/03-commands.md#create-github-app) command. Once you've gone through the CLI command, it should produce a YAML file in the root of the project which you can then use as an `include` in your 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 8541d64465ee5..aacd60af8c84d 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 @@ -39,7 +39,7 @@ For this tutorial, we've automatically exported all permissions from this file ( :::note Note -We use a separate `todo-list-common` package since all permissions authorized by your plugin should be exported from a ["common-library" package](https://backstage.io/docs/local-dev/cli-build-system#package-roles). This allows Backstage integrators to reference them in frontend components as well as permission policies. +We use a separate `todo-list-common` package since all permissions authorized by your plugin should be exported from a ["common-library" package](https://backstage.io/docs/tooling/cli/build-system#package-roles). This allows Backstage integrators to reference them in frontend components as well as permission policies. ::: diff --git a/docs/plugins/create-a-plugin.md b/docs/plugins/create-a-plugin.md index 481b610e4e1e7..d80e9cd57ef00 100644 --- a/docs/plugins/create-a-plugin.md +++ b/docs/plugins/create-a-plugin.md @@ -11,7 +11,7 @@ A Backstage Plugin adds functionality to Backstage. To create a new frontend plugin, make sure you've run `yarn install` and installed dependencies, then run the following on your command line (a shortcut to invoking the -[`backstage-cli new --select plugin`](../local-dev/cli-commands.md#new)) +[`backstage-cli new --select plugin`](../tooling/cli/03-commands.md#new)) from the root of your project. ```bash diff --git a/docs/plugins/testing.md b/docs/plugins/testing.md index bc212a2581412..a97b3d8166bf4 100644 --- a/docs/plugins/testing.md +++ b/docs/plugins/testing.md @@ -369,4 +369,4 @@ Note: wrapping in the test application **requires** you to do a `find()` or ## Debugging Jest Tests -You can find it [here](https://backstage.io/docs/local-dev/cli-build-system#debugging-jest-tests) +You can find it [here](https://backstage.io/docs/tooling/cli/build-system#debugging-jest-tests) diff --git a/docs/references/glossary.md b/docs/references/glossary.md index 6db16443e2676..906260e710dca 100644 --- a/docs/references/glossary.md +++ b/docs/references/glossary.md @@ -201,7 +201,7 @@ A service that hosts [packages](#package). The most prominent example is [NPM](h ## Package Role -The declared role of a package, see [package roles](../local-dev/cli-build-system.md#package-roles). +The declared role of a package, see [package roles](../tooling/cli/02-build-system.md#package-roles). ## Permission (core Backstage plugin) diff --git a/docs/releases/v1.20.0.md b/docs/releases/v1.20.0.md index 921b8219fbf9f..0d0075aa41d4a 100644 --- a/docs/releases/v1.20.0.md +++ b/docs/releases/v1.20.0.md @@ -12,7 +12,7 @@ A huge thanks to the whole team of maintainers and contributors as well as the a ### Support for experimental type build has been removed -The `--experimental-type-build` option is no longer supported by any commands in the Backstage CLI. Existing usage should be migrated to using [subpath exports](https://backstage.io/docs/local-dev/cli-build-system#subpath-exports) instead. +The `--experimental-type-build` option is no longer supported by any commands in the Backstage CLI. Existing usage should be migrated to using [subpath exports](https://backstage.io/docs/tooling/cli/build-system#subpath-exports) instead. ### Experimental support for Vite ⚡ diff --git a/docs/local-dev/cli-overview.md b/docs/tooling/cli/01-overview.md similarity index 82% rename from docs/local-dev/cli-overview.md rename to docs/tooling/cli/01-overview.md index 4ab8bb21aca19..78c4b2755fbf5 100644 --- a/docs/local-dev/cli-overview.md +++ b/docs/tooling/cli/01-overview.md @@ -1,5 +1,5 @@ --- -id: cli-overview +id: overview title: Overview description: Overview of the Backstage CLI --- @@ -7,12 +7,12 @@ description: Overview of the Backstage CLI ## Introduction A goal of Backstage is to provide a delightful developer experience in and -around the project. Creating new [apps](../references/glossary.md#app) and -[plugins](../references/glossary.md#plugin) should be simple, iteration +around the project. Creating new [apps](../../references/glossary.md#app) and +[plugins](../../references/glossary.md#plugin) should be simple, iteration speed should be fast, and the overhead of maintaining custom tooling should be minimal. As a part of accomplishing this goal, Backstage provides its own build system and tooling, delivered primarily through the -[`@backstage/cli`](https://www.npmjs.com/package/@backstage/cli) [package](../references/glossary.md#package). When +[`@backstage/cli`](https://www.npmjs.com/package/@backstage/cli) [package](../../references/glossary.md#package). When creating an app using [`@backstage/create-app`](https://www.npmjs.com/package/@backstage/create-app), you receive a project that's already prepared with a typical setup and package @@ -23,8 +23,8 @@ Under the hood the CLI uses [Webpack](https://webpack.js.org/) for bundling, [Jest](https://jestjs.io/) for testing, and [eslint](https://eslint.org/) for linting. It also includes tooling for working within Backstage apps, for example for keeping the app up to date and verifying static configuration. For a more -in-depth look into the tooling, see the [build system](./cli-build-system.md) -page, and for a list of commands, see the [commands](./cli-commands.md) page. +in-depth look into the tooling, see the [build system](./02-build-system.md) +page, and for a list of commands, see the [commands](./03-commands.md) page. While the Backstage tooling is opinionated in how it works, it is also possible to use your own tooling either partially or fully. For example, the CLI provides diff --git a/docs/local-dev/cli-build-system.md b/docs/tooling/cli/02-build-system.md similarity index 99% rename from docs/local-dev/cli-build-system.md rename to docs/tooling/cli/02-build-system.md index ddcfa44cf54ed..bfdb21f45fb7b 100644 --- a/docs/local-dev/cli-build-system.md +++ b/docs/tooling/cli/02-build-system.md @@ -1,5 +1,5 @@ --- -id: cli-build-system +id: build-system title: Build System description: A deep dive into the Backstage build system --- @@ -74,7 +74,7 @@ implemented in a typical Backstage app. ## Package Roles -> Package roles were introduced in March 2022. To migrate existing projects, see the [migration guide](../tutorials/package-role-migration.md). +> Package roles were introduced in March 2022. To migrate existing projects, see the [migration guide](../../tutorials/package-role-migration.md). The Backstage build system uses the concept of package roles in order to help keep configuration lean, provide utility and tooling, and enable optimizations. A package @@ -258,7 +258,7 @@ When building CommonJS or ESM output, the build commands will always use `src/index.ts` as the entrypoint. All non-relative modules imports are considered external, meaning the Rollup build will only compile the source code of the package itself. All import statements of external dependencies, even within the same -[monorepo](../references/glossary.md#monorepo), will stay intact. +[monorepo](../../references/glossary.md#monorepo), will stay intact. The build of the type definitions works quite differently. The entrypoint of the type definition build is the relative location of the package within the @@ -308,7 +308,7 @@ support for them instead. ### Frontend Production The frontend production bundling creates your typical web content -[bundle](../references/glossary.md#bundle), all contained within a single +[bundle](../../references/glossary.md#bundle), all contained within a single folder, ready for static serving. It is used when building packages with the `'frontend'` role, and unlike the development bundling there is no way to build a production bundle of an individual plugin. diff --git a/docs/local-dev/cli-commands.md b/docs/tooling/cli/03-commands.md similarity index 95% rename from docs/local-dev/cli-commands.md rename to docs/tooling/cli/03-commands.md index 173d616e61d3c..234d0d04b764f 100644 --- a/docs/local-dev/cli-commands.md +++ b/docs/tooling/cli/03-commands.md @@ -1,5 +1,5 @@ --- -id: cli-commands +id: commands title: Commands description: Descriptions of all commands available in the CLI. --- @@ -102,7 +102,7 @@ Options: ## package start -Starts the package for local development. See the frontend and backend development parts in the build system [bundling](./cli-build-system.md#bundling) section for more details. +Starts the package for local development. See the frontend and backend development parts in the build system [bundling](./02-build-system.md#bundling) section for more details. ```text Usage: backstage-cli package start [options] @@ -119,7 +119,7 @@ Options: ## package build -Build an individual package based on its role. See the build system [building](./cli-build-system.md#building) and [bundling](./cli-build-system.md#bundling) sections for more details. +Build an individual package based on its role. See the build system [building](./02-build-system.md#building) and [bundling](./02-build-system.md#bundling) sections for more details. ```text Usage: backstage-cli package build [options] @@ -139,7 +139,7 @@ Options: Lint a package. In addition to the default `eslint` behavior, this command will include TypeScript files, treat warnings as errors, and default to linting the entire directory if no specific files are listed. For more information, see the -build system [linting](./cli-build-system.md#linting) section. +build system [linting](./02-build-system.md#linting) section. ```text Usage: backstage-cli package lint [options] @@ -165,7 +165,7 @@ a yarn workspaces monorepo by automatically creating one grouped configuration that includes all packages that have `backstage-cli test` in their package `test` script. -For more information about configuration overrides and editor support, see the [Jest Configuration section](./cli-build-system.md#jest-configuration) in the build system documentation. +For more information about configuration overrides and editor support, see the [Jest Configuration section](./02-build-system.md#jest-configuration) in the build system documentation. ```text Usage: backstage-cli package test [options] @@ -190,7 +190,7 @@ Delete cache directories This command should be added as `scripts.prepack` in all packages. It enables packaging- and publish-time overrides for fields inside `packages.json`. -For more details, see the build system [publishing](./cli-build-system.md#publishing) section. +For more details, see the build system [publishing](./02-build-system.md#publishing) section. ```text Usage: backstage-cli package prepack [options] @@ -369,8 +369,8 @@ Usage: backstage-cli build-workspace [options] ## create-github-app Creates a GitHub App in your GitHub organization. This is an alternative to -token-based [GitHub integration](../integrations/github/locations.md). See -[GitHub Apps for Backstage Authentication](../integrations/github/github-apps.md). +token-based [GitHub integration](../../integrations/github/locations.md). See +[GitHub Apps for Backstage Authentication](../../integrations/github/github-apps.md). Launches a browser to create the App through GitHub and saves the result as a YAML file that can be referenced in the GitHub integration configuration. diff --git a/docs/local-dev/debugging.md b/docs/tooling/local-dev/debugging.md similarity index 100% rename from docs/local-dev/debugging.md rename to docs/tooling/local-dev/debugging.md diff --git a/docs/local-dev/linking-local-packages.md b/docs/tooling/local-dev/linking-local-packages.md similarity index 100% rename from docs/local-dev/linking-local-packages.md rename to docs/tooling/local-dev/linking-local-packages.md diff --git a/docs/tutorials/package-role-migration.md b/docs/tutorials/package-role-migration.md index db84defd9183e..dcd8a66ee66e0 100644 --- a/docs/tutorials/package-role-migration.md +++ b/docs/tutorials/package-role-migration.md @@ -10,7 +10,7 @@ information about the change can be found in the [original RFC](https://github.c Package roles are implemented through a well-known `"backstage"."role"` field in the `package.json` of each package. There are a handful of roles defined so far, and it -is not possible to use values outside the [set of predefined roles](../local-dev/cli-build-system.md#package-roles). +is not possible to use values outside the [set of predefined roles](../tooling/cli/02-build-system.md#package-roles). With roles in place in all packages, the Backstage CLI is able to automatically determine how to handle each package. For example, the different build commands @@ -55,7 +55,7 @@ yarn backstage-cli migrate package-roles The automatic detection is not perfect, so it is recommended to manually review the roles that were assigned to each package. -You can use the [package role definitions](../local-dev/cli-build-system.md#package-roles) as a reference. +You can use the [package role definitions](../tooling/cli/02-build-system.md#package-roles) as a reference. ### Step 2 - Migrate package scripts @@ -85,7 +85,7 @@ If you in the end do not want to use this exact script setup, it is still recomm ### Step 3 - Migrate package ESLint configurations -An area that has been simplified as part of the move to package roles is the ESLint configuration. Rather than having each package select which configuration they want (and getting it wrong), they now use a shared configuration factory that utilizes the package role. You can read more about the new configuration setup in the [build system documentation](../local-dev/cli-build-system.md#linting). +An area that has been simplified as part of the move to package roles is the ESLint configuration. Rather than having each package select which configuration they want (and getting it wrong), they now use a shared configuration factory that utilizes the package role. You can read more about the new configuration setup in the [build system documentation](../tooling/cli/02-build-system.md#linting). To migrate the ESLint configuration of all packages in your project, run the following command: @@ -97,7 +97,7 @@ This will migrate all existing `.eslintrc.js` that extend the old configuration ### Step 4 - Use `backstage-cli repo` -The Backstage CLI recently introduced a new `repo` command category, which houses commands that operate on an entire monorepo at once. These commands work particularly well once packages have been migrated to use roles, as that allows for some very effective optimizations. It is typically much faster to use these commands compared to using tools like `lerna`, as they're able to avoid the overhead of calling package scripts through `yarn` and can operate on multiple packages at once. You can read more about the `repo` command in the [CLI command documentation](../local-dev/cli-commands.md#repo-build). +The Backstage CLI recently introduced a new `repo` command category, which houses commands that operate on an entire monorepo at once. These commands work particularly well once packages have been migrated to use roles, as that allows for some very effective optimizations. It is typically much faster to use these commands compared to using tools like `lerna`, as they're able to avoid the overhead of calling package scripts through `yarn` and can operate on multiple packages at once. You can read more about the `repo` command in the [CLI command documentation](../tooling/cli/03-commands.md#repo-build). The way to execute this step of the migration is not as well defined as the previous steps, as it depends on what your development and CI/CD setup looks like. Look for the following patterns to replace in your root `package.json` as well as CI/CD setup: diff --git a/microsite/sidebars.json b/microsite/sidebars.json index a3d9f4dbece12..5ddd2f97f1391 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -69,19 +69,6 @@ "getting-started/keeping-backstage-updated", "getting-started/concepts" ], - "Local Development": [ - { - "type": "category", - "label": "CLI", - "items": [ - "local-dev/cli-overview", - "local-dev/cli-build-system", - "local-dev/cli-commands" - ] - }, - "local-dev/linking-local-packages", - "local-dev/debugging" - ], "Core Features": [ { "type": "category", @@ -358,6 +345,25 @@ ] } ], + "Tooling": [ + { + "type": "category", + "label": "Backstage CLI", + "items": [ + "tooling/cli/overview", + "tooling/cli/build-system", + "tooling/cli/commands" + ] + }, + { + "type": "category", + "label": "Local Development", + "items": [ + "tooling/local-dev/linking-local-packages", + "tooling/local-dev/debugging" + ] + } + ], "Deployment": [ "deployment/index", "deployment/scaling", diff --git a/mkdocs.yml b/mkdocs.yml index 66ce7d8defc8c..026e76d531134 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,12 +33,6 @@ nav: - Create a component: 'getting-started/create-a-component.md' - Keeping Backstage Updated: 'getting-started/keeping-backstage-updated.md' - Key Concepts: 'getting-started/concepts.md' - - Local Development: - - CLI: - - Overview: 'local-dev/cli-overview.md' - - Build System: 'local-dev/cli-build-system.md' - - Commands: 'local-dev/cli-commands.md' - - Linking in Local Packages: 'local-dev/linking-local-packages.md' - Core Features: - Software Catalog: - Overview: 'features/software-catalog/index.md' @@ -178,6 +172,14 @@ nav: - Contributing New Providers: 'auth/add-auth-provider.md' - Service to Service Auth: 'auth/service-to-service-auth.md' - Troubleshooting Auth: 'auth/troubleshooting.md' + - Tooling: + - Backstage CLI: + - Overview: 'tooling/cli/01-overview.md' + - Build System: 'tooling/cli/02-build-system.md' + - Commands: 'tooling/cli/03-commands.md' + - Local Development: + - Linking in Local Packages: 'tooling/local-dev/linking-local-packages.md' + - Debugging Backstage: 'tooling/local-dev/debugging.md' - Deployment: - Deploying Backstage: 'deployment/index.md' - Scaling: 'deployment/scaling.md' diff --git a/packages/backend-legacy/README.md b/packages/backend-legacy/README.md index 20e68dc746c38..0de555fe70ca8 100644 --- a/packages/backend-legacy/README.md +++ b/packages/backend-legacy/README.md @@ -31,7 +31,7 @@ The backend starts up on port 7007 per default. ### Debugging -The backend is a node process that can be inspected to allow breakpoints and live debugging. To enable this, pass the `--inspect` flag to [backend:dev](https://backstage.io/docs/local-dev/cli-build-system#backend-development). +The backend is a node process that can be inspected to allow breakpoints and live debugging. To enable this, pass the `--inspect` flag to [backend:dev](https://backstage.io/docs/tooling/cli/build-system#backend-development). To debug the backend in [Visual Studio Code](https://code.visualstudio.com/): diff --git a/packages/cli-node/src/roles/types.ts b/packages/cli-node/src/roles/types.ts index a913ff29b6060..d6eff04541cf0 100644 --- a/packages/cli-node/src/roles/types.ts +++ b/packages/cli-node/src/roles/types.ts @@ -15,7 +15,7 @@ */ /** - * Backstage package role, see {@link https://backstage.io/docs/local-dev/cli-build-system#package-roles | docs}. + * Backstage package role, see {@link https://backstage.io/docs/tooling/cli/build-system#package-roles | docs}. * * @public */