docs: added initial package role migration docs

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

docs/tutorials/package-role-migration.md

@@ -0,0 +1,143 @@
+---
+id: package-role-migration
+title: Package Role Migration
+description: Guide for how to migrate packages to use the new role utility
+---
+
+The Backstage CLI has introduced the concept of package roles, whose purpose is to
+enable more powerful tooling and leaner package configuration. More background and
+information about the change can be found in the [original RFC](https://github.com/backstage/backstage/issues/8729).
+
+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 value outside the set of predefined roles. Some examples of
+these roles are `frontend-plugin`, `node-library`, and `backend-plugin-module`.
+
+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
+have been replaced by a single one that instead knows how to build each role.
+The test and lint configurations are also selected automatically based on the role, and
+a new category of `repo` commands have been introduced in the CLI, which are able
+to operate across all packages at once.
+
+Package roles have been used in the Backstage main repository for a while, and
+we now recommend that all Backstage projects are migrated to use package roles.
+
+## Migration
+
+In order to make the migration as smooth as possible, `@backstage/cli` provides
+a number of migration utilities. Using these in combination with some manual review
+and optional steps should be all you need to migrate to package roles in most projects.
+
+Before you begin the migration, make sure you have updated to the most recent version of
+the `@backstage/cli`.
+
+### TL;DR, Step 1-4:
+
+This is a sorter version of all of the steps below, in case you're in a hurry.
+
+Run the following commands:
+
+```sh
+yarn backstage-cli migrate package-roles
+yarn backstage-cli migrate package-scripts
+yarn backstage-cli migrate package-lint-configs
+```
+
+Have a look at the new commands under `yarn backstage-cli repo`, and switch to them wherever you can. They tend to be a much faster compared to their `lerna` equivalents.
+
+### Step 1 - Add package roles
+
+The first step is to add the `"backstage"."role"` field to each package. This
+is done by running the following command:
+
+```sh
+yarn backstage-cli migrate package-roles
+```
+
+This will add the role field to each package in your project, detecting the role
+based on existing information like what build scripts are in place and the package name.
+
+This automatic detection is not perfect, so it recommended to manually review the
+roles that were assigned to each package.
+You can use the [package role definitions](./not-found#TODO) as a reference.
+
+### Step 2 - Migrate package scripts
+
+The migration to package roles also introduces a new `package` command category to the CLI.
+Each command under the `package` category is designed to be mapped directly to an entry in `"scripts"` in `package.json`. These commands replace the existing commands like `build`, `app:build`, `lint` and `test`. They look something like this:
+
+```json
+{
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    ...
+  }
+}
+```
+
+Every package role each has a fixed set of recommended scripts. It is strongly recommended that you use these scripts, as it allows for optimizations in other parts of the CLI. You can migrate to using all of these scripts by running the following command:
+
+```sh
+yarn backstage-cli migrate package-scripts
+```
+
+The migration command also carries over any existing flags that were being passed in the old scripts.
+
+If you in the end do not want to use this exact script setup, it is still recommended to migrate to using the `package` commands, as the top-level commands will be deprecated and removed. If you don't want to use package roles either, you can pass an explicit role to some of the package commands, for example `yarn backstage-cli package build --role web-library`.
+
+### 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.
+
+A minimal `.eslintrc.js` configuration now looks like this:
+
+```js
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);
+```
+
+You can provide custom overrides for each package using the optional second argument:
+
+```js
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname, {
+  ignorePatterns: ['templates/'],
+  rules: {
+    'jest/expect-expect': 'off',
+  },
+});
+```
+
+The configuration factory also provides utilities for extending the configuration in ways that are otherwise very cumbersome to do with plain ESLint, particularly for rules like `no-restricted-syntax`. You can read more about that in the [build system documentation](./not-found#TODO).
+
+To migrate the ESLint configuration of all packages in your project, run the following command:
+
+```sh
+yarn backstage-cli migrate package-lint-configs
+```
+
+This will migrate all existing `.eslintrc.js` that extend the old configuration from `@backstage/cli`, as well as carry over any additional 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`. You can read more about the `repo` command in the [CLI command documentation](./not-found#TODO).
+
+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:
+
+- Commands that lint the entire repo should be replaced with `yarn backstage-cli repo lint` along with a `--since` flag if needed. For example this:
+
+  ```sh
+  lerna run lint --since origin/master --
+  ```
+
+  would be replaced by the following:
+
+  ```sh
+  backstage-cli repo lint --since origin/master
+  ```
+
+- In places where the entire repo is being built, use `yarn backstage-cli repo build`, which also supports the `--since` flag. The migration here is a bit more nuanced as it depends why you are building all packages.
+  - If you are building all packages to **verify** that you are able to build them, you most likely want `backstage-cli repo build --all`. The `--all` flag signals that bundled packages like `packages/app` and `packages/backend` should be build as well. Pair this up with a `--since` flag in CI to avoid needing to build all packages.
+  - If you are building all packages to **publish** them, then `backstage-cli repo build` is enough, as it builds all published packages.
+  - If you are building all packages to **deploy** them, you likely don't want to use the `repo` command at all, simply call `yarn build` in the packages you want to deploy instead. For example, if you are deploying the backend with a docker host build, it's enough to call `yarn build` inside `packages/backend`.

microsite/sidebars.json

@@ -273,6 +273,7 @@
     "Tutorials": [
       "tutorials/journey",
       "tutorials/quickstart-app-plugin",
+      "tutorials/package-role-migration",
       "tutorials/migrating-away-from-core",
       "tutorials/configuring-plugin-databases",
       "tutorials/switching-sqlite-postgres",

mkdocs.yml

@@ -170,6 +170,7 @@ nav:
       - Deprecations: 'api/deprecations.md'
   - Tutorials:
       - Future developer journey: 'tutorials/journey.md'
+      - Package Role Migration: 'tutorials/package-role-migration.md'
       - Migrating away from @backstage/core: 'tutorials/migrating-away-from-core.md'
       - Adding Custom Plugin to Existing Monorepo App: 'tutorials/quickstart-app-plugin.md'
       - Switching Backstage from SQLite to PostgreSQL: 'tutorials/switching-sqlite-postgres.md'