diff --git a/.changeset/migrate-1713465727782.md b/.changeset/migrate-1713465727782.md new file mode 100644 index 0000000000..29c186cd48 --- /dev/null +++ b/.changeset/migrate-1713465727782.md @@ -0,0 +1,7 @@ +--- +'@backstage/plugin-adr': patch +'@backstage/plugin-adr-backend': patch +'@backstage/plugin-adr-common': patch +--- + +These packages have been migrated to the [backstage/community-plugins](https://github.com/backstage/community-plugins) repository. diff --git a/.changeset/migrate-1713465834005.md b/.changeset/migrate-1713465834005.md new file mode 100644 index 0000000000..29c186cd48 --- /dev/null +++ b/.changeset/migrate-1713465834005.md @@ -0,0 +1,7 @@ +--- +'@backstage/plugin-adr': patch +'@backstage/plugin-adr-backend': patch +'@backstage/plugin-adr-common': patch +--- + +These packages have been migrated to the [backstage/community-plugins](https://github.com/backstage/community-plugins) repository. diff --git a/plugins/adr-backend/README.md b/plugins/adr-backend/README.md index 73af5137ba..81dd865846 100644 --- a/plugins/adr-backend/README.md +++ b/plugins/adr-backend/README.md @@ -1,117 +1,3 @@ -# ADR Backend +# Deprecated -This ADR backend plugin is primarily responsible for the following: - -- Provides a `DefaultAdrCollatorFactory`, which can be used in the search backend to index ADR documents associated with entities to your Backstage Search. - -- Provides endpoints that use UrlReaders for getting ADR documents (used in the [ADR frontend plugin](../adr/README.md)). - -## Install - -## Setup your `integrations` config - -First off you'll need to setup your `integrations` config inside your `app-config.yaml`. You can skip this step if it's already setup previously, and if you need help configuring this you can read the [integrations documentation](https://backstage.io/docs/integrations/) - -### Up and Running - -Here's how to get the backend up and running: - -1. First we need to add the `@backstage/plugin-adr-backend` package to your backend: - -```sh -# From your Backstage root directory -yarn --cwd packages/backend add @backstage/plugin-adr-backend -``` - -2. Then we will create a new file named `packages/backend/src/plugins/adr.ts`, and add the - following to it: - -```ts -import { createRouter } from '@backstage/plugin-adr-backend'; -import { Router } from 'express'; -import { PluginEnvironment } from '../types'; - -export default async function createPlugin( - env: PluginEnvironment, -): Promise { - return await createRouter({ - reader: env.reader, - cacheClient: env.cache.getClient(), - logger: env.logger, - }); -} -``` - -3. Next we wire this into the overall backend router, edit `packages/backend/src/index.ts`: - -```ts -import adr from './plugins/adr'; -// ... -async function main() { - // ... - // Add this line under the other lines that follow the useHotMemoize pattern - const adrEnv = useHotMemoize(module, () => createEnv('adr')); - // ... - // Insert this line under the other lines that add their routers to apiRouter in the same way - apiRouter.use('/adr', await adr(adrEnv)); -``` - -4. Now run `yarn start-backend` from the repo root - -### New Backend System - -The ADR backend plugin has support for the [new backend system](https://backstage.io/docs/backend-system/), here's how you can set that up: - -In your `packages/backend/src/index.ts` make the following changes: - -```diff - const backend = createBackend(); - -+ backend.add(import('@backstage/plugin-adr-backend')); - -// ... other feature additions - - backend.start(); -``` - -## Indexing ADR documents for search - -Before you are able to start indexing ADR documents to search, you need to go through the [search getting started guide](https://backstage.io/docs/features/search/getting-started). - -When you have your `packages/backend/src/plugins/search.ts` file ready to make modifications, install this plugin and add the following code snippet to add the `DefaultAdrCollatorFactory`. Also make sure to set up the frontend [ADR plugin](../adr/README.md) so search results can be routed correctly. - -```bash -# From your Backstage root directory -yarn --cwd packages/backend add @backstage/plugin-adr-backend -``` - -```ts -import { DefaultAdrCollatorFactory } from '@backstage/plugin-adr-backend'; - -... - -indexBuilder.addCollator({ - schedule, - factory: DefaultAdrCollatorFactory.fromConfig({ - cache: env.cache, - config: env.config, - discovery: env.discovery, - logger: env.logger, - reader: env.reader, - tokenManager: env.tokenManager, - }), -}); -``` - -### Parsing custom ADR document formats - -By default, the `DefaultAdrCollatorFactory` will parse and index documents that follow [MADR v3.0.0](https://github.com/adr/madr/tree/3.0.0) and [MADR v2.x](https://github.com/adr/madr/tree/2.1.2) standard file name and template format. If you use a different ADR format and file name convention, you can configure `DefaultAdrCollatorFactory` with custom `adrFilePathFilterFn` and `parser` options (see type definitions for details): - -```ts -DefaultAdrCollatorFactory.fromConfig({ - ... - parser: myCustomAdrParser, - adrFilePathFilterFn: myCustomAdrFilePathFilter, - ... -}) -``` +This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-adr-backend` instead. diff --git a/plugins/adr-backend/package.json b/plugins/adr-backend/package.json index 4230954e11..4974fe4d4b 100644 --- a/plugins/adr-backend/package.json +++ b/plugins/adr-backend/package.json @@ -1,31 +1,35 @@ { "name": "@backstage/plugin-adr-backend", "version": "0.4.14", - "main": "src/index.ts", - "types": "src/index.ts", - "license": "Apache-2.0", + "backstage": { + "role": "backend-plugin", + "moved": "@backstage-community/plugin-adr-backend" + }, "publishConfig": { "access": "public", "main": "dist/index.cjs.js", "types": "dist/index.d.ts" }, - "backstage": { - "role": "backend-plugin" - }, "homepage": "https://backstage.io", "repository": { "type": "git", "url": "https://github.com/backstage/backstage", "directory": "plugins/adr-backend" }, + "license": "Apache-2.0", + "main": "src/index.ts", + "types": "src/index.ts", + "files": [ + "dist" + ], "scripts": { - "start": "backstage-cli package start", "build": "backstage-cli package build", - "lint": "backstage-cli package lint", - "test": "backstage-cli package test", "clean": "backstage-cli package clean", + "lint": "backstage-cli package lint", "prepack": "backstage-cli package prepack", - "postpack": "backstage-cli package postpack" + "postpack": "backstage-cli package postpack", + "start": "backstage-cli package start", + "test": "backstage-cli package test" }, "dependencies": { "@backstage/backend-common": "workspace:^", @@ -50,7 +54,5 @@ "@types/supertest": "^2.0.8", "supertest": "^6.1.3" }, - "files": [ - "dist" - ] + "deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-adr-backend instead." } diff --git a/plugins/adr-common/README.md b/plugins/adr-common/README.md index 38b5b7433c..7c074e84b8 100644 --- a/plugins/adr-common/README.md +++ b/plugins/adr-common/README.md @@ -1,3 +1,3 @@ -# ADR Common +# Deprecated -Common types and functionalities for the ADR plugin. +This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-adr-common` instead. diff --git a/plugins/adr-common/package.json b/plugins/adr-common/package.json index 603ce8448b..87abce09ca 100644 --- a/plugins/adr-common/package.json +++ b/plugins/adr-common/package.json @@ -3,7 +3,8 @@ "version": "0.2.22", "description": "Common functionalities for the adr plugin", "backstage": { - "role": "common-library" + "role": "common-library", + "moved": "@backstage-community/plugin-adr-common" }, "publishConfig": { "access": "public", @@ -41,5 +42,6 @@ }, "devDependencies": { "@backstage/cli": "workspace:^" - } + }, + "deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-adr-common instead." } diff --git a/plugins/adr/README.md b/plugins/adr/README.md index 3e8647a8fa..aa3e89ce1f 100644 --- a/plugins/adr/README.md +++ b/plugins/adr/README.md @@ -1,161 +1,3 @@ -# Architecture Decision Records (ADR) Plugin +# Deprecated -Welcome to the ADR plugin! - -This plugin allows you to explore ADRs (Architecture Decision Records) associated with your entities, as well as discover ADRs across other entities using Backstage Search. Use this to inform your own architectural decisions based on the experiences of previous projects. - -![ADR tab](./docs/adr-tab.png) - -## Setup - -1. Install this plugin: - -```bash -# From your Backstage root directory -yarn --cwd packages/app add @backstage/plugin-adr -``` - -2. Make sure the [ADR backend plugin](../adr-backend/README.md) is installed. - -3. [Configure integrations](https://backstage.io/docs/integrations/) for all sites you would like to pull ADRs from. - -### Entity Pages - -1. Add the plugin as a tab to your Entity pages: - -```jsx -// In packages/app/src/components/catalog/EntityPage.tsx -import { EntityAdrContent, isAdrAvailable } from '@backstage/plugin-adr'; - -... -// Note: Add to any other Pages as well (e.g. defaultEntityPage and websiteEntityPage) -const serviceEntityPage = ( - - {/* other tabs... */} - - - - -``` - -2. Add `backstage.io/adr-location` annotation to your `catalog-info.yaml`: - -```yaml -metadata: - annotations: - backstage.io/adr-location: -``` - -The value for `backstage.io/adr-location` should be a path relative to your `catalog-info.yaml` file or a absolute URL to the directory which contains your ADR markdown files. - -For example, if you have the following directory structure, you would set `backstage.io/adr-location: docs/adrs`: - -``` -repo-root/ - README.md - src/ - catalog-info.yaml - docs/ - adrs/ - 0001-use-adrs.md - 0002-use-cloud.md -``` - -### Search - -First, make sure to setup Backstage Search with the [ADR backend plugin](../adr-backend/README.md). -Afterwards, add the following code snippet to use `AdrSearchResultListItem` when the type of the search results is `adr`: - -```tsx -// In packages/app/src/components/search/SearchPage.tsx -import { AdrSearchResultListItem } from '@backstage/plugin-adr'; -import { AdrDocument } from '@backstage/plugin-adr-common'; - -... -// Optional - Add type to side pane -, - }, - ]} -/> -... - -// In results - - {({ results }) => ( - - {results.map(({ type, document, highlight, rank }) => { - switch (type) { - ... - case 'adr': - return ( - - ); - ... - } - })} - - )} - -``` - -## Custom ADR formats - -By default, this plugin will parse ADRs according to the format specified by the [Markdown Architecture Decision Record (MADR) v2.x template](https://github.com/adr/madr/tree/2.1.2) or the [Markdown Any Decision Record (MADR) 3.x template](https://github.com/adr/madr/tree/3.0.0). If your ADRs are written using a different format, you can apply the following customizations to correctly identify and parse your documents: - -### Custom Filename/Path Format - -In order to ensure the plugin fetches the correct ADR files (e.g. ignoring your template file), you can pass in an optional `filePathFilterFn` parameter to `EntityAdrContent` which will be called with each file path relative to the ADR location specified by `backstage.io/adr-location`. For example, the follow custom filter function will ignore the ADR template file and include files with a specific naming convention including those under a specified sub-directory: - -```tsx -const myCustomFilterFn: AdrFilePathFilterFn = (path: string): boolean => { - if (path === '0000-adr-template.md') { - return false; - } - // Match all files following the pattern NNNN-title-with-dashes.md including those under decided-adrs/ - return /^(decided-adrs\/)?\d{4}-.+\.md$/.test(path); -} - -... - - -``` - -### Custom Content Decorators - -Your ADR Markdown content will typically be rendered in the UI as is with the exception of relative links/embeds being rewritten as absolute URLs so they can be linked correctly (e.g. `./my-diagram.png` => `/my-diagram.png`). Depending on your ADR format, you may want to apply additional transformations to the content (e.g. hiding or formatting front matter in a different way). You can do so by passing in a list of custom content decorators for the optional `contentDecorators` parameter. Note that passing in this parameter will override the default decorators. If you want to include the default ones, make sure to add them as well: - -```tsx -import { - AdrReader, - ... -} from '@backstage/plugin-adr'; - -... - -const myCustomDecorator: AdrContentDecorator = ({ content }) => { - return { content: applyCustomContentTransformation(content) }; -}; - -... - - -``` +This package has been moved to the [backstage-community/plugins](https://github.com/backstage/community-plugins) repository. Migrate to using `@backstage-community/plugin-adr` instead. diff --git a/plugins/adr/package.json b/plugins/adr/package.json index a9908fe98c..bdf54391e8 100644 --- a/plugins/adr/package.json +++ b/plugins/adr/package.json @@ -2,7 +2,8 @@ "name": "@backstage/plugin-adr", "version": "0.6.17", "backstage": { - "role": "frontend-plugin" + "role": "frontend-plugin", + "moved": "@backstage-community/plugin-adr" }, "publishConfig": { "access": "public" @@ -70,5 +71,6 @@ "react": "^16.13.1 || ^17.0.0 || ^18.0.0", "react-dom": "^16.13.1 || ^17.0.0 || ^18.0.0", "react-router-dom": "6.0.0-beta.0 || ^6.3.0" - } + }, + "deprecated": "This package has been moved to the backstage/community-plugins repository. You should migrate to using @backstage-community/plugin-adr instead." }