diff --git a/plugins/adr-backend/README.md b/plugins/adr-backend/README.md index 79b5fe13ed..ab81c34c82 100644 --- a/plugins/adr-backend/README.md +++ b/plugins/adr-backend/README.md @@ -4,6 +4,8 @@ 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 a ADR documents (used in the [ADR frontend plugin](../adr/README.md)). + ## 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). diff --git a/plugins/adr-backend/src/service/router.ts b/plugins/adr-backend/src/service/router.ts index c70f7763e7..1b896e2805 100644 --- a/plugins/adr-backend/src/service/router.ts +++ b/plugins/adr-backend/src/service/router.ts @@ -18,6 +18,7 @@ import { UrlReader } from '@backstage/backend-common'; import express from 'express'; import Router from 'express-promise-router'; +/** @public */ export async function createRouter(reader: UrlReader): Promise { const router = Router(); router.use(express.json()); diff --git a/plugins/adr/README.md b/plugins/adr/README.md index 2888ff2f07..2d3c2be9a4 100644 --- a/plugins/adr/README.md +++ b/plugins/adr/README.md @@ -4,7 +4,7 @@ Welcome to the ADR plugin! This plugin allows you to browse ADRs associated with your entities as well as a way to discover ADRs across others entities via Backstage Search. Use this to learn from the past experience of other projects to guide your own architecture decisions. -NOTE: This plugin currently only supports entities/ADRs registered via GitHub integration. +NOTE: By default, this plugin only supports entities/ADRs registered via GitHub integration. To get ADRs from other sites, see the [Using ADR plugin with sites other than GitHub](#using-adr-plugin-with-sites-other-than-github) section. ## Setup @@ -77,6 +77,29 @@ case 'adr': ); ``` +## Using ADR plugin with sites other than GitHub + +By default, the ADR plugin will only be able to retrieve ADRs through GitHub. If you would like to use it with other sites (for instance, AzureDevops): + +1. Make sure the [ADR backend plugin](../adr-backend/README.md) is installed. +2. [Configure an integration](https://backstage.io/docs/integrations/) for the site you would like to pull ADRs from. +3. Set the adrFileFetcher property on EntityAdrContent to urlReadersAdrFileFetcher: + +```jsx +// In packages/app/src/components/catalog/EntityPage.tsx +import { EntityAdrContent, isAdrAvailable, urlReaderAdrFileFetcher } from '@backstage/plugin-adr'; + +... + +const serviceEntityPage = ( + + {/* other tabs... */} + + + + +``` + ## Custom ADR formats By default, this plugin will parse ADRs according to the format specified by the [Markdown Architecture Decision Record (MADR)](https://adr.github.io/madr/) template. If your ADRs are written using a different format, you can apply the following customizations to correctly identify and parse your documents: diff --git a/plugins/adr/src/hooks/adrFileFetcher.ts b/plugins/adr/src/hooks/adrFileFetcher.ts index 2ddbe00434..c0402df628 100644 --- a/plugins/adr/src/hooks/adrFileFetcher.ts +++ b/plugins/adr/src/hooks/adrFileFetcher.ts @@ -40,14 +40,36 @@ const useAdrApi = ( }; }; +/** + * Represents something that is capable of fetching a listing of adr files at a provided url + * and fetching the contents of an adr file at a provided url. + * + * @public + */ export interface AdrFileFetcher { + /** + * A hook to get a listing of adr files that exist at the provided url + * + * @param url The url to get files from + */ useGetAdrFilesAtUrl: (url: string) => any; + + /** + * A hook to get the contents of the adr file at the provided url + * + * @param url The url of the adr file + */ useReadAdrFileAtUrl: (url: string) => any; } const getAdrFilesEndpoint = 'getAdrFilesAtUrl'; const readAdrFileEndpoint = 'readAdrFileAtUrl'; +/** + * An AdrFileFetcher that uses UrlReaders to fetch adr files + * + * @public + */ export const urlReaderAdrFileFetcher: AdrFileFetcher = { useGetAdrFilesAtUrl: function (url: string) { const discoveryApi = useApi(discoveryApiRef); @@ -63,6 +85,11 @@ export const urlReaderAdrFileFetcher: AdrFileFetcher = { }, }; +/** + * An AdrFileFetcher that uses the useOctokitRequest hook for fetching adr files + * + * @public + */ export const octokitAdrFileFetcher: AdrFileFetcher = { useGetAdrFilesAtUrl: (url: string) => useOctokitRequest(url), useReadAdrFileAtUrl: (url: string) => useOctokitRequest(url), diff --git a/plugins/adr/src/index.ts b/plugins/adr/src/index.ts index 84012ccb7a..1b8406330f 100644 --- a/plugins/adr/src/index.ts +++ b/plugins/adr/src/index.ts @@ -22,3 +22,4 @@ export { isAdrAvailable } from '@backstage/plugin-adr-common'; export * from './components/AdrReader'; export { adrPlugin, EntityAdrContent } from './plugin'; export * from './search'; +export * from './hooks/adrFileFetcher';