paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 20 Packages Projects Releases Wiki Activity

Deprecate packages

Browse Source 
Signed-off-by: blam <ben@blam.sh>
This commit is contained in:
blam
2024-04-18 20:43:59 +02:00
parent 33fbebadf1
commit 4af1f1bf00
8 changed files with 43 additions and 295 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/migrate-1713465727782.md
+7
View File
@@ -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.
.changeset/migrate-1713465834005.md
+7
View File
@@ -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.
plugins/adr-backend/README.md
+2 -116
View File
@@ -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<Router> {
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.
plugins/adr-backend/package.json
+15 -13
View File
@@ -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."
}
plugins/adr-common/README.md
+2 -2
View File
@@ -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.
plugins/adr-common/package.json
+4 -2
View File
@@ -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."
}
plugins/adr/README.md
+2 -160
View File
@@ -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 = (
<EntityLayout>
{/* other tabs... */}
<EntityLayout.Route if={isAdrAvailable} path="/adrs" title="ADRs">
<EntityAdrContent />
</EntityLayout.Route>
</EntityLayout>
```
2. Add `backstage.io/adr-location` annotation to your `catalog-info.yaml`:
```yaml
metadata:
annotations:
backstage.io/adr-location: <RELATIVE_PATH_TO_ADR_FILES_DIR>
```
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
<SearchType.Accordion
name="Result Type"
defaultValue="software-catalog"
types={[
...
{
value: 'adr',
name: 'Architecture Decision Records',
icon: <DocsIcon />,
},
]}
/>
...
// In results
<SearchResult>
{({ results }) => (
<List>
{results.map(({ type, document, highlight, rank }) => {
switch (type) {
...
case 'adr':
return (
<AdrSearchResultListItem
key={document.location}
// Not required if you're leveraging the new search results extensions available in v1.11+
// https://backstage.io/docs/features/search/how-to-guides#2-using-an-extension-in-your-backstage-app
result={document as AdrDocument}
/>
);
...
}
})}
</List>
)}
</SearchResult>
```
## 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);
}
...
<EntityAdrContent filePathFilterFn={myCustomFilterFn} />
```
### 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` => `<ABSOLUTE_ADR_DIR_URL>/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) };
};
...
<EntityAdrContent contentDecorators={[
AdrReader.decorators.createRewriteRelativeLinksDecorator(),
AdrReader.decorators.createRewriteRelativeEmbedsDecorator(),
AdrReader.decorators.createFrontMatterFormatterDecorator(),
myCustomDecorator,
]}
/>
```
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.
plugins/adr/package.json
+4 -2
View File
@@ -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."
}