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

Merge pull request #3 from backstage/master

Browse Source 
pull from upstream
This commit is contained in:
Brett Wright
2021-07-05 08:41:45 +02:00
committed by GitHub
parent af15e108d9 c654b10e91
commit 20589b4835
1433 changed files with 8789 additions and 37124 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/angry-hounds-bow.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/integration': patch
---
Do not throw in `ScmIntegration` `byUrl` for invalid URLs
.changeset/beige-ladybugs-sip.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/core-components': patch
---
Improve UX of the Sidebar by adding SidebarScrollWrapper component allowing the user to scroll through Plugins & Shortcuts on smaller screens. Prevent the Sidebar from opening on click on small devices
.changeset/config.json
+4 -1
View File
@@ -6,5 +6,8 @@
"access": "public",
"baseBranch": "master",
"updateInternalDependencies": "patch",
"ignore": []
"ignore": [],
"___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
"onlyUpdatePeerDependentsWhenOutOfRange": true
}
}
.changeset/cuddly-donuts-whisper.md
-54
View File
@@ -1,54 +0,0 @@
---
'@backstage/plugin-explore': patch
---
Refactors the explore plugin to be more customizable. This includes the following non-breaking changes:
- Introduce new `ExploreLayout` page which can be used to create a custom `ExplorePage`
- Refactor `ExplorePage` to use a new `ExploreLayout` component
- Exports existing `DomainExplorerContent`, `GroupsExplorerContent`, & `ToolExplorerContent` components
- Allows `title` props to be customized
Create a custom explore page in `packages/app/src/components/explore/ExplorePage.tsx`.
```tsx
import {
DomainExplorerContent,
ExploreLayout,
} from '@backstage/plugin-explore';
import React from 'react';
import { InnserSourceExplorerContent } from './InnserSourceExplorerContent';
export const ExplorePage = () => {
return (
<ExploreLayout
title="Explore the ACME corp ecosystem"
subtitle="Browse our ecosystem"
>
<ExploreLayout.Route path="domains" title="Domains">
<DomainExplorerContent />
</ExploreLayout.Route>
<ExploreLayout.Route path="inner-source" title="InnerSource">
<AcmeInnserSourceExplorerContent />
</ExploreLayout.Route>
</ExploreLayout>
);
};
export const explorePage = <ExplorePage />;
```
Now register the new explore page in `packages/app/src/App.tsx`.
```diff
+ import { explorePage } from './components/explore/ExplorePage';
const routes = (
<FlatRoutes>
- <Route path="/explore" element={<ExplorePage />} />
+ <Route path="/explore" element={<ExplorePage />}>
+ {explorePage}
+ </Route>
</FlatRoutes>
);
```
.changeset/eighty-deers-jam.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-catalog-import': patch
---
More helpful error message when trying to import by folder from non-github
.changeset/fair-falcons-scream.md
+7
View File
@@ -0,0 +1,7 @@
---
'@backstage/core-components': patch
'@backstage/plugin-explore': patch
---
- Enhanced core `Button` component to open external links in new tab.
- Replaced the use of `Button` component from material by `core-components` in tools card.
.changeset/few-windows-whisper.md
-8
View File
@@ -1,8 +0,0 @@
---
'@backstage/core-app-api': patch
'@backstage/core-plugin-api': patch
'@backstage/plugin-catalog': patch
'@backstage/plugin-scaffolder': patch
---
Adding `FeatureFlag` component and treating `FeatureFlags` as first class citizens to composability API
.changeset/five-baboons-explain.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/dev-utils': minor
---
Removed support for deprecated registered plugin routes. All routes now need to be added using `addPage` instead.
.changeset/flat-donkeys-rhyme.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/catalog-model': minor
---
Changed the regex to validate names following the Kubernetes validation rule, this allow to be more permissive validating the name of the object in Backstage.
.changeset/forty-dodos-own.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/catalog-client': patch
---
Return entities sorted alphabetically by ref
.changeset/friendly-bikes-double.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/cli': patch
---
updated plugin template to generate path equals plugin id for the root page
.changeset/good-jars-turn.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/plugin-search': patch
---
Use the `identityApi` to forward authorization headers to the `search-backend`
.changeset/gorgeous-timers-cover.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/techdocs-common': patch
---
Fix openStack swift publisher encoding issue. Remove utf8 forced encoding on binary files
.changeset/heavy-numbers-refuse.md
-10
View File
@@ -1,10 +0,0 @@
---
'@backstage/plugin-api-docs': minor
'@backstage/plugin-cost-insights': minor
'@backstage/plugin-gcp-projects': minor
'@backstage/plugin-gitops-profiles': minor
'@backstage/plugin-newrelic': minor
'@backstage/plugin-welcome': minor
---
**BREAKING CHANGE** Remove deprecated route registrations, meaning that it is no longer enough to only import the plugin in the app and the exported page extension must be used instead.
.changeset/honest-cars-glow.md
+54
View File
@@ -0,0 +1,54 @@
---
'@backstage/backend-common': patch
---
Added a `readUrl` method to the `UrlReader` interface that allows for complex response objects and is intended to replace the `read` method. This new method is currently optional to implement which allows for a soft migration to `readUrl` instead of `read` in the future.
The main use case for `readUrl` returning an object instead of solely a read buffer is to allow for additional metadata such as ETag, which is a requirement for more efficient catalog processing.
The `GithubUrlReader` and `GitlabUrlReader` readers fully implement `readUrl`. The other existing readers implement the new method but do not propagate or return ETags.
While the `readUrl` method is not yet required, it will be in the future, and we already log deprecation warnings when custom `UrlReader` implementations that do not implement `readUrl` are used. We therefore recommend that any existing custom implementations are migrated to implement `readUrl`.
The old `read` and the new `readUrl` methods can easily be implemented using one another, but we recommend moving the chunk of the implementation to the new `readUrl` method as `read` is being removed, for example this:
```ts
class CustomUrlReader implements UrlReader {
read(url: string): Promise<Buffer> {
const res = await fetch(url);
if (!res.ok) {
// error handling ...
}
return Buffer.from(await res.text());
}
}
```
Can be migrated to something like this:
```ts
class CustomUrlReader implements UrlReader {
read(url: string): Promise<Buffer> {
const res = await this.readUrl(url);
return res.buffer();
}
async readUrl(
url: string,
_options?: ReadUrlOptions,
): Promise<ReadUrlResponse> {
const res = await fetch(url);
if (!res.ok) {
// error handling ...
}
const buffer = Buffer.from(await res.text());
return { buffer: async () => buffer };
}
}
```
While there is no usage of the ETag capability yet in the main Backstage packages, you can already add it to your custom implementations. To do so, refer to the documentation of the `readUrl` method and surrounding types, and the existing implementation in `packages/backend-common/src/reading/GithubUrlReader.ts`.
.changeset/metal-badgers-carry.md
-25
View File
@@ -1,25 +0,0 @@
---
'@backstage/plugin-catalog-backend': patch
'@backstage/plugin-catalog-backend-module-msgraph': patch
---
Move `MicrosoftGraphOrgReaderProcessor` from `@backstage/plugin-catalog-backend`
to `@backstage/plugin-catalog-backend-module-msgraph`.
The `MicrosoftGraphOrgReaderProcessor` isn't registered by default anymore, if
you want to continue using it you have to register it manually at the catalog
builder:
1. Add dependency to `@backstage/plugin-catalog-backend-module-msgraph` to the `package.json` of your backend.
2. Add the processor to the catalog builder:
```typescript
// packages/backend/src/plugins/catalog.ts
builder.addProcessor(
MicrosoftGraphOrgReaderProcessor.fromConfig(config, {
logger,
}),
);
```
For more configuration details, see the [README of the `@backstage/plugin-catalog-backend-module-msgraph` package](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend-module-msgraph/README.md).
.changeset/metal-cycles-run.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/plugin-techdocs': patch
---
Fix the overlapping between the sidebar and the tabs navigation when enabled in mkdocs (features: navigation.tabs)
.changeset/odd-humans-exercise.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/cli': patch
---
Make the `create-github-app` command disable webhooks by default.
.changeset/perfect-gifts-compete.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/plugin-auth-backend': patch
---
Don't export the `defaultGoogleAuthProvider`
.changeset/plenty-kings-shout.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/cli': patch
---
chore: bump `@typescript-eslint/eslint-plugin` from 4.26.0 to 4.27.0
.changeset/popular-rice-wonder.md
-8
View File
@@ -1,8 +0,0 @@
---
'@backstage/plugin-catalog': patch
'@backstage/plugin-catalog-backend': patch
'@backstage/plugin-scaffolder': patch
'@backstage/plugin-scaffolder-backend': patch
---
Moved installation instructions from the main [backstage.io](https://backstage.io) documentation to the package README file. These instructions are not generally needed, since the plugin comes installed by default with `npx @backstage/create-app`.
.changeset/rich-trees-chew.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/cli': patch
---
chore: bump `@spotify/eslint-config-typescript` from 9.0.0 to 10.0.0
.changeset/rotten-walls-cross.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-catalog-backend': patch
---
Make use of the new `readUrl` method on `UrlReader` from `@backstage/backend-common`.
.changeset/serious-falcons-greet.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/integration': patch
---
Fix downloads from repositories located at bitbucket.org
.changeset/seven-adults-act.md
-25
View File
@@ -1,25 +0,0 @@
---
'@backstage/plugin-auth-backend': patch
---
Adds support for custom sign-in resolvers and profile transformations for the
Google auth provider.
Adds an `ent` claim in Backstage tokens, with a list of
[entity references](https://backstage.io/docs/features/software-catalog/references)
related to your signed-in user's identities and groups across multiple systems.
Adds an optional `providerFactories` argument to the `createRouter` exported by
the `auth-backend` plugin.
Updates `BackstageIdentity` so that
- `idToken` is deprecated in favor of `token`
- An optional `entity` field is added which represents the entity that the user is represented by within Backstage.
More information:
- [The identity resolver documentation](https://backstage.io/docs/auth/identity-resolver)
explains the concepts and shows how to implement your own.
- The [From Identity to Ownership](https://github.com/backstage/backstage/issues/4089)
RFC contains details about how this affects ownership in the catalog
.changeset/shy-garlics-tap.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/create-app': patch
---
Use SidebarScrollWrapper to improve responsiveness of the current sidebar. Change: Wrap a section of SidebarItems with this component to enable scroll for smaller screens. It can also be used in sidebar plugins (see shortcuts plugin for an example).
.changeset/silent-horses-fry.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/core-components': patch
---
Fix error in error panel, and console warnings about DOM nesting pre inside p
.changeset/silent-ways-laugh.md
-6
View File
@@ -1,6 +0,0 @@
---
'@backstage/plugin-catalog-backend-module-msgraph': patch
---
Allow customizations of `MicrosoftGraphOrgReaderProcessor` by passing an
optional `groupTransformer`, `userTransformer`, and `organizationTransformer`.
.changeset/smart-insects-care.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/plugin-catalog': patch
---
Disambiguated titles of `EntityDependencyOfComponentsCard` and `EntityDependsOnComponentsCard`.
.changeset/techdocs-cool-rivers-suffer.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/plugin-techdocs': patch
---
Refactor the implicit logic from `<Reader />` into an explicit state machine. This resolves some state synchronization issues when content is refreshed or rebuilt in the backend.
.changeset/techdocs-poor-forks-repeat.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/plugin-techdocs-backend': patch
---
Return a `304 Not Modified` from the `/sync/:namespace/:kind/:name` endpoint if nothing was built. This enables the caller to know whether a refresh of the docs page will return updated content (-> `201 Created`) or not (-> `304 Not Modified`).
.changeset/violet-maps-smell.md
+6
View File
@@ -0,0 +1,6 @@
---
'@backstage/backend-common': patch
'@backstage/plugin-scaffolder-backend': patch
---
add defaultBranch property for publish GitHub action
.changeset/weak-needles-peel.md
-5
View File
@@ -1,5 +0,0 @@
---
'@backstage/plugin-scaffolder-backend': patch
---
Correctly recognize whether the cookiecutter command exists
.github/codecov.yml
+8 -4
View File
@@ -14,11 +14,15 @@ coverage:
# Since Backstage is a mono repo, flags here help in getting the code coverage of individual packages.
# Documentation: https://docs.codecov.io/docs/flags
flags:
core:
core-app-api:
paths:
- packages/core/
- packages/core-app-api/
carryforward: true
core-api:
core-components:
paths:
- packages/core-api/
- packages/core-components/
carryforward: true
core-plugin-api:
paths:
- packages/core-plugin-api/
carryforward: true
.github/styles/vocab.txt
+9
View File
@@ -52,10 +52,12 @@ cookiecutter
css
Datadog
dataflow
dayjs
deadnaming
debounce
Debounce
declaratively
deduplicated
deps
destructured
dev
@@ -120,6 +122,7 @@ Knex
kubectl
kubernetes
kubernetes
ldap
learnings
Leasot
lerna
@@ -173,6 +176,7 @@ oidc
Okta
onboarding
Onboarding
orgs
pagerduty
pageview
parallelization
@@ -204,6 +208,8 @@ repo
Repo
repos
rerender
Reusability
reusability
rollbar
Rollbar
Rollup
@@ -221,6 +227,7 @@ seb
semlas
semver
Serverless
siloed
Sinon
Snyk
sourcemaps
@@ -267,12 +274,14 @@ transpilation
transpiled
truthy
ui
unbreak
unmanaged
unregister
unregistration
untracked
upvote
url
URLs
utils
validator
validators
.github/workflows/chromatic-storybook-test.yml
+1 -2
View File
@@ -4,8 +4,7 @@ on:
paths:
- '.github/workflows/chromatic-storybook-test.yml'
- 'packages/storybook/**'
- 'packages/core/src/components/**'
- 'packages/core/src/layout/**'
- 'packages/core-components/src/**'
jobs:
chromatic:
.github/workflows/master.yml
+3 -2
View File
@@ -119,8 +119,9 @@ jobs:
yarn lerna -- run test -- --coverage
bash <(curl -s https://codecov.io/bash)
# Upload code coverage for some specific flags. Also see .codecov.yml
bash <(curl -s https://codecov.io/bash) -f packages/core/coverage/* -F core
bash <(curl -s https://codecov.io/bash) -f packages/core-api/coverage/* -F core-api
bash <(curl -s https://codecov.io/bash) -f packages/core-app-api/coverage/* -F core-app-api
bash <(curl -s https://codecov.io/bash) -f packages/core-components/coverage/* -F core-components
bash <(curl -s https://codecov.io/bash) -f packages/core-plugin-api/coverage/* -F core-plugin-api
env:
BACKSTAGE_TEST_DATABASE_POSTGRES13_CONNECTION_STRING: postgresql://postgres:postgres@localhost:${{ job.services.postgres13.ports[5432] }}
BACKSTAGE_TEST_DATABASE_POSTGRES9_CONNECTION_STRING: postgresql://postgres:postgres@localhost:${{ job.services.postgres9.ports[5432] }}
.github/workflows/microsite-with-storybook-deploy.yml
+1 -1
View File
@@ -7,7 +7,7 @@ on:
paths:
- '.github/workflows/microsite-with-storybook-deploy.yml'
- 'packages/storybook/**'
- 'packages/core/src/**'
- 'packages/core-components/src/**'
- 'microsite/**'
- 'docs/**'
ADOPTERS.md
+6 -2
View File
@@ -1,7 +1,7 @@
| Organization | Contact | Description of Use |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Spotify](https://www.spotify.com) | [@leemills83](https://github.com/leemills83) | Main interface towards all of Spotify's infrastructure and technical documentation. |
| [bol.com](https://www.bol.com) | [@RoyJacobs](https://github.com/RoyJacobs) | Initial work being done to unify platform tooling. |
| [bol.com](https://www.bol.com) | [@sagacity](https://github.com/sagacity) | Initial work being done to unify platform tooling. |
| [DFDS](https://www.dfds.com) | [@carlsendk](https://github.com/carlsendk) | V2 self-service platform. |
| [Roadie](https://roadie.io) | [@dtuite](https://github.com/dtuite) | Hosted, managed Backstage with easy set-up |
| [Roku](https://www.roku.com) | [@timurista](https://github.com/timurista) | Initial work on Cloud engineering service platform. |
@@ -32,4 +32,8 @@
| [PagerDuty](https://www.pagerduty.com/) | [Mark Shaw](https://github.com/markshawtoronto) | Developer portal, initially focused on software templates and tech-docs. |
| [MoonShiner](https://moonshiner.at) | [Fabian Hippmann](https://github.com/FabianHippmann) | Developer portal - helps us keep track of our customer projects, onboard new developers & improve our development process 🌕🚀🧑‍🚀 |
| [FundApps](https://www.fundapps.co/) | [Elliot Greenwood](https://github.com/egnwd) | Developer Portal - A place for us to keep track of our projects and documentation for all services and processes |
| [DAZN](https://dazn.com/) | [Lou Bichard](https://twitter.com/loujaybee), [Marco Crivellaro](https://github.com/crivetechie) | Ingesting all of DAZN's repos for the catalog, migrating our internal platform apps (pull request boards, release information, inner source marketplace etc) to Backstage plugins (where applicable). |
| [DAZN](https://dazn.com/) | [Lou Bichard](https://twitter.com/loujaybee), [Marco Crivellaro](https://github.com/crivetechie), [Alex Hollerith](mailto:alex.hollerith@dazn.com) | Ingesting all of DAZN's repos for the catalog, migrating our internal platform apps (pull request boards, release information, inner source marketplace etc) to Backstage plugins (where applicable). |
| [HelloFresh](https://www.hellofresh.de/) | [@iammuho](https://github.com/iammuho), [@ElenaForester](https://github.com/ElenaForester), [@diegomarangoni](https://github.com/diegomarangoni) | Our developer portal at HelloFresh - Spread across an organisation of 500+ engineers globally. |
| [FactSet](https://www.factset.com/) | [@kuangp](https://github.com/kuangp) | Developer portal to provide discoverability to all internal components, APIs, documentation, and scaffold templates with integrations to our internal infrastructure tools. |
| [Workrise](https://www.workrise.com/) | [Michael Rode](https://github.com/michaelrode) | Developer portal, main gateway to our infrastructure, documentation and internal tooling. |
| [RedVentures](https://www.redventures.com/) | [Chris Diaz](https://github.com/codingdiaz) | Developer portal that brings everything an engineer needs to provide value into a single pane of glass. |
README.md
+6 -4
View File
@@ -2,6 +2,8 @@
# [Backstage](https://backstage.io)
_During the month of July the majority of the maintainers will be on summer vacation 🏖️ Development will continue as usual, but expect a slower pace for discussions and PR reviews. Why not take this opportunity to [build a plugin](https://backstage.io/docs/plugins/)?_
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![CNCF Status](https://img.shields.io/badge/cncf%20status-sandbox-blue.svg)](https://www.cncf.io/projects)
[![Main CI Build](https://github.com/backstage/backstage/workflows/Main%20Master%20Build/badge.svg)](https://github.com/backstage/backstage/actions?query=workflow%3A%22Main+Master+Build%22)
@@ -12,15 +14,15 @@
## What is Backstage?
[Backstage](https://backstage.io/) is an open platform for building developer portals. Powered by a centralized service catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly — without compromising autonomy.
[Backstage](https://backstage.io/) is an open platform for building developer portals. Powered by a centralized software catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly — without compromising autonomy.
Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.
![service-catalog](https://backstage.io/blog/assets/6/header.png)
![software-catalog](https://backstage.io/blog/assets/6/header.png)
Out of the box, Backstage includes:
- [Backstage Service Catalog](https://backstage.io/docs/features/software-catalog/software-catalog-overview) for managing all your software (microservices, libraries, data pipelines, websites, ML models, etc.)
- [Backstage Software Catalog](https://backstage.io/docs/features/software-catalog/software-catalog-overview) for managing all your software (microservices, libraries, data pipelines, websites, ML models, etc.)
- [Backstage Software Templates](https://backstage.io/docs/features/software-templates/software-templates-index) for quickly spinning up new projects and standardizing your tooling with your organization’s best practices
- [Backstage TechDocs](https://backstage.io/docs/features/techdocs/techdocs-overview) for making it easy to create, maintain, find, and use technical documentation, using a "docs like code" approach
- Plus, a growing ecosystem of [open source plugins](https://github.com/backstage/backstage/tree/master/plugins) that further expand Backstage’s customizability and functionality
@@ -38,7 +40,7 @@ Check out [the documentation](https://backstage.io/docs/getting-started) on how
## Documentation
- [Main documentation](https://backstage.io/docs)
- [Service Catalog](https://backstage.io/docs/features/software-catalog/software-catalog-overview)
- [Software Catalog](https://backstage.io/docs/features/software-catalog/software-catalog-overview)
- [Architecture](https://backstage.io/docs/overview/architecture-overview) ([Decisions](https://backstage.io/docs/architecture-decisions/adrs-overview))
- [Designing for Backstage](https://backstage.io/docs/dls/design)
- [Storybook - UI components](https://backstage.io/storybook)
contrib/docs/tutorials/authenticate-api-requests.md
+82 -2
View File
@@ -4,7 +4,7 @@ The Backstage backend APIs are by default available without authentication. To a
API requests from frontend plugins include an authorization header with a Backstage identity token acquired when the user logs in. By adding a middleware that verifies said token to be valid and signed by Backstage, non-authenticated requests can be blocked with a 401 Unauthorized response.
Note that this means Backstage will stop working for guests, as no token is issued for them.
**NOTE**: Enabling this means that Backstage will stop working for guests, as no token is issued for them.
As techdocs HTML pages load assets without an Authorization header the code below also sets a token cookie when the user logs in (and when the token is about to expire).
@@ -99,7 +99,7 @@ async function main() {
```typescript
// packages/app/src/App.tsx from a create-app deployment
import { discoveryApiRef, useApi } from '@backstage/core';
import { discoveryApiRef, useApi } from '@backstage/core-plugin-api';
// ...
@@ -181,3 +181,83 @@ const app = createApp({
// ...
```
**NOTE**: Most Backstage frontend plugins come with the support for the `IdentityApi`.
In case you already have a dozen of internal ones, you may need to update those too.
Assuming you follow the common plugin structure, the changes to your front-end may look like:
```diff
// plugins/internal-plugin/src/api.ts
- import {createApiRef} from '@backstage/core';
+ import {createApiRef, IdentityApi} from '@backstage/core';
import {Config} from '@backstage/config';
// ...
type MyApiOptions = {
configApi: Config;
+ identityApi: IdentityApi;
// ...
}
interface MyInterface {
getData(): Promise<MyData[]>;
}
export class MyApi implements MyInterface {
private configApi: Config;
+ private identityApi: IdentityApi;
// ...
constructor(options: MyApiOptions) {
this.configApi = options.configApi;
+ this.identityApi = options.identityApi;
}
async getMyData() {
const backendUrl = this.configApi.getString('backend.baseUrl');
+ const token = await this.identityApi.getIdToken();
const requestUrl = `${backendUrl}/api/data/`;
- const response = await fetch(requestUrl);
+ const response = await fetch(
requestUrl,
{ headers: { Authorization: `Bearer ${token}` } },
);
// ...
}
```
and
```diff
// plugins/internal-plugin/src/plugin.ts
import {
configApiRef,
createApiFactory,
createPlugin,
+ identityApiRef,
} from '@backstage/core';
import {mypluginPageRouteRef} from './routeRefs';
import {MyApi, myApiRef} from './api';
export const plugin = createPlugin({
id: 'my-plugin',
routes: {
mainPage: mypluginPageRouteRef,
},
apis: [
createApiFactory({
api: myApiRef,
deps: {
configApi: configApiRef,
+ identityApi: identityApiRef,
},
- factory: ({configApi}) =>
- new MyApi({ configApi }),
+ factory: ({configApi, identityApi}) =>
+ new MyApi({ configApi, identityApi }),
}),
],
});
```
contrib/docs/tutorials/aws-alb-aad-oidc-auth.md
+1 -1
View File
@@ -51,7 +51,7 @@ The Backstage App needs a SignInPage when authentication is required.
When using ALB authentication Backstage will only be loaded once the user has successfully authenticated; we won't need to display a SignIn page, however we will need to create a dummy SignIn component that can refresh the token.
- edit `packages/app/src/App.tsx`
- import the following two additional definitions from `@backstage/core`: `useApi`, `configApiRef`; these will be used to check whether Backstage is running locally or behind an ALB
- import the following two additional definitions from `@backstage/core-plugin-api`: `useApi`, `configApiRef`; these will be used to check whether Backstage is running locally or behind an ALB
- add the following definition just before the app is created (`const app = createApp`):
```ts
contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md
+1
View File
@@ -26,6 +26,7 @@ import 'global-agent/bootstrap';
```sh
export GLOBAL_AGENT_HTTP_PROXY=$HTTP_PROXY
export GLOBAL_AGENT_NO_PROXY=$NO_PROXY
yarn start
```
contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md
+2 -3
View File
@@ -5,6 +5,7 @@ ExampleComponent.tsx reference
```tsx
import React from 'react';
import { Typography, Grid } from '@material-ui/core';
import { identityApiRef, useApi } from '@backstage/core-plugin-api';
import {
InfoCard,
Header,
@@ -13,9 +14,7 @@ import {
ContentHeader,
HeaderLabel,
SupportButton,
identityApiRef,
useApi,
} from '@backstage/core';
} from '@backstage/core-components';
import { ExampleFetchComponent } from '../ExampleFetchComponent';
export const ExampleComponent = () => {
contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md
+2 -7
View File
@@ -6,13 +6,8 @@ ExampleFetchComponent.tsx reference
import React from 'react';
import { useAsync } from 'react-use';
import Alert from '@material-ui/lab/Alert';
import {
Table,
TableColumn,
Progress,
githubAuthApiRef,
useApi,
} from '@backstage/core';
import { githubAuthApiRef, useApi } from '@backstage/core-plugin-api';
import { Table, TableColumn, Progress } from '@backstage/core-components';
import { graphql } from '@octokit/graphql';
const query = `{
docs/api/utility-apis.md
+22 -18
View File
@@ -23,18 +23,18 @@ during their entire life cycle.
Each Utility API is tied to an `ApiRef` instance, which is a global singleton
object without any additional state or functionality, its only purpose is to
reference Utility APIs. `ApiRef`s are created using `createApiRef`, which is
exported by `@backstage/core`. There are many
exported by `@backstage/core-plugin-api`. There are many
[predefined Utility APIs](../reference/utility-apis/README.md) defined in
`@backstage/core`, and they're all exported with a name of the pattern
`*ApiRef`, for example `errorApiRef`.
`@backstage/core-plugin-api`, and they're all exported with a name of the
pattern `*ApiRef`, for example `errorApiRef`.
To access one of the Utility APIs inside a React component, use the `useApi`
hook exported by `@backstage/core`, or the `withApis` HOC if you prefer class
components. For example, the `ErrorApi` can be accessed like this:
hook exported by `@backstage/core-plugin-api`, or the `withApis` HOC if you
prefer class components. For example, the `ErrorApi` can be accessed like this:
```tsx
import React from 'react';
import { useApi, errorApiRef } from '@backstage/core';
import { useApi, errorApiRef } from '@backstage/core-plugin-api';
export const MyComponent = () => {
const errorApi = useApi(errorApiRef);
@@ -52,9 +52,9 @@ Note that there is no explicit type given for `ErrorApi`. This is because the
`errorApiRef` has the type embedded, and `useApi` is able to infer the type.
Also note that consuming Utility APIs is not limited to plugins, it can be done
from any component inside Backstage, including the ones in `@backstage/core`.
The only requirement is that they are beneath the `AppProvider` in the react
tree.
from any component inside Backstage, including the ones in
`@backstage/core-plugin-api`. The only requirement is that they are beneath the
`AppProvider` in the react tree.
## Supplying APIs
@@ -71,8 +71,11 @@ For example, this is the default `ApiFactory` for the `ErrorApi`:
createApiFactory({
api: errorApiRef,
deps: { alertApi: alertApiRef },
factory: ({ alertApi }) =>
new ErrorAlerter(alertApi, new ErrorApiForwarder()),
factory: ({ alertApi }) => {
const errorApi = new ErrorAlerter(alertApi, new ErrorApiForwarder());
UnhandledErrorForwarder.forward(errorApi, { hidden: false });
return errorApi;
},
});
```
@@ -98,13 +101,13 @@ app, and the app itself.
### Core APIs
Starting with the Backstage core library, it provides implementations for all of
the core APIs. The core APIs are the ones exported by `@backstage/core`, such as
the `errorApiRef` and `configApiRef`. You can find a full list of them
[here](../reference/utility-apis/README.md).
the core APIs. The core APIs are the ones exported by
`@backstage/core-plugin-api`, such as the `errorApiRef` and `configApiRef`. You
can find a full list of them [here](../reference/utility-apis/README.md).
The core APIs are loaded for any app created with `createApp` from
`@backstage/core`, which means that there is no step that needs to be taken to
include these APIs in an app.
`@backstage/core-plugin-api`, which means that there is no step that needs to be
taken to include these APIs in an app.
### Plugin APIs
@@ -210,8 +213,9 @@ implement the `ErrorApi`, as it is checked by the type embedded in the
Plugins are free to define their own Utility APIs. Simply define the TypeScript
interface for the API, and create an `ApiRef` using `createApiRef` exported from
`@backstage/core`. Also be sure to provide at least one implementation of the
API, and to declare a default factory for the API in `createPlugin`.
`@backstage/core-plugin-api`. Also be sure to provide at least one
implementation of the API, and to declare a default factory for the API in
`createPlugin`.
Custom Utility APIs can be either public or private, which is up to the plugin
to choose. Private APIs do not expose an external API surface, and it's
docs/architecture-decisions/adr004-module-export-structure.md
+3 -3
View File
@@ -6,8 +6,8 @@ description: Architecture Decision Record (ADR) log on Module Export Structure
## Context
With a growing number of exports of packages like `@backstage/core`, it is
becoming more and more difficult to answer questions such as
With a growing number of exports of packages like `@backstage/core-components`,
it is becoming more and more difficult to answer questions such as
> Is the export in this module also exported by the package?
@@ -86,7 +86,7 @@ import { helperFunc } from '../../lib/UtilityX/helper';
## Consequences
We will actively work to rework the export structure in our codebase,
prioritizing the library packages such as `@backstage/core` and
prioritizing the library packages such as `@backstage/core-components` and
`@backstage/backend-common`.
If possible, we will add tools, such as lint rules, to help enforce the export
docs/architecture-decisions/adr011-plugin-package-structure.md
+6
View File
@@ -35,6 +35,8 @@ example `catalog` or `techdocs`):
- `x`: Contains the main frontend code of the plugin.
- `x-backend`: Contains the main backend code of the plugin.
- `x-backend-module-<name>`: Contains optional modules related to the backend
plugin.
- `x-react`: Contains shared widgets, hooks and similar that both the plugin
itself (`x`) and third-party frontend plugins can depend on.
- `x-node`: Contains utilities for backends that both the plugin backend itself
@@ -61,6 +63,10 @@ We will actively migrate existing packages that are part of a plugin to the
`plugins/catalog-common` we might want to do an exception here, as it's a very
central package.
We will actively migrate optional features of backend plugins into separate
`x-backend-module-<name>` packages, for example the more specialized processors
in the catalog backend.
The limited set of rules might not be sufficient in the future. If additional
packages are required, we will revisit this decision and extend the pattern.
docs/assets/software-catalog/service-catalog-home.png → docs/assets/software-catalog/software-catalog-home.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 303 KiB

After

Width:  |  Height:  |  Size: 303 KiB

docs/auth/index.md
+2 -1
View File
@@ -66,7 +66,8 @@ built-in providers:
```diff
# packages/app/src/App.tsx
+ import { githubAuthApiRef, SignInProviderConfig, SignInPage } from '@backstage/core';
+ import { githubAuthApiRef } from '@backstage/core-plugin-api';
+ import { SignInProviderConfig, SignInPage } from '@backstage/core-components';
+ const githubProvider: SignInProviderConfig = {
+ id: 'github-auth-provider',
docs/auth/oauth.md
+4 -4
View File
@@ -14,7 +14,7 @@ to various third party APIs.
There are occasions when the user wants to perform actions towards third party
services that require authorization via OAuth. Backstage provides standardized
[Utility APIs](../api/utility-apis.md) such as the
[GoogleAuthApi](https://github.com/backstage/backstage/blob/master/packages/core-api/src/apis/definitions/auth.ts)
[GoogleAuthApi](https://github.com/backstage/backstage/blob/master/packages/core-plugin-api/src/apis/definitions/auth.ts)
for that use-case. Backstage also includes a set of implementations of these
APIs that integrate with the
[auth-backend](https://github.com/backstage/backstage/tree/master/plugins/auth-backend)
@@ -38,7 +38,7 @@ choose an account to log in with, and accept or reject the request. If the user
accepts the login request, a token is issued, and any holder of the token can
use it to make authenticated requests towards the third party service.
## OAuth in @backstage/core-api and auth-backend
## OAuth in @backstage/core-app-api and auth-backend
The default OAuth implementation in Backstage is based on an OAuth server-side
offline access flow, which means that it uses the backend as a helper in order
@@ -59,8 +59,8 @@ easier to make authenticated requests inside a plugin.
The following describes the OAuth flow implemented by the
[auth-backend](https://github.com/backstage/backstage/tree/master/plugins/auth-backend)
and
[DefaultAuthConnector](https://github.com/backstage/backstage/blob/master/packages/core-api/src/lib/AuthConnector/DefaultAuthConnector.ts)
in `@backstage/core-api`.
[DefaultAuthConnector](https://github.com/backstage/backstage/blob/master/packages/core-app-api/src/lib/AuthConnector/DefaultAuthConnector.ts)
in `@backstage/core-app-api`.
Component and APIs can request Access or ID Tokens from any available Auth
provider. If there already exists a cached fresh token that covers (at least)
docs/auth/using-auth.md
+9 -8
View File
@@ -45,8 +45,8 @@ pieces in place that can be used.
#### Identity for Plugin Developers
As a plugin developer, there are two main touchpoints for identities: the
`IdentityApi` exported by `@backstage/core` via the `identityApiRef`, and a not
yet existing middleware exported by `@backstage/backend-common`.
`IdentityApi` exported by `@backstage/core-plugin-api` via the `identityApiRef`,
and a not yet existing middleware exported by `@backstage/backend-common`.
The `IdentityApi` gives access to the signed-in user's identity in the frontend.
It provides access to the user's ID, lightweight profile information, and an ID
@@ -61,8 +61,9 @@ https://github.com/backstage/backstage/issues/1435.
If you're setting up your own Backstage app, or want to add a new identity
provider, there are three touchpoints: the frontend auth APIs in
`@backstage/core-api`, the backend auth providers in `auth-backend`, and the
`SignInPage` component configured in the Backstage app via `createApp`.
`@backstage/core-app-api` and `@backstage/core-plugin-api`, the backend auth
providers in `auth-backend`, and the `SignInPage` component configured in the
Backstage app via `createApp`.
The frontend APIs and backend providers are tightly coupled together for each
auth provider, and together they implement an e2e auth flow. Only some auth
@@ -81,10 +82,10 @@ The final piece of the puzzle is the `SignInPage` component that can be
configured as part of the app. Without a sign-in page, Backstage will fall back
to a `guest` identity for all users, without any ID token. To enable sign-in, a
`SignInPage` needs to be configured, which in turn has to supply a user to the
app. The `@backstage/core` package provides a basic sign-in page that allows
both the user and the app developer to choose between a couple of different
sign-in methods, or to designate a single provider that may also be logged in to
automatically.
app. The `@backstage/core-components` package provides a basic sign-in page that
allows both the user and the app developer to choose between a couple of
different sign-in methods, or to designate a single provider that may also be
logged in to automatically.
## Further Reading
docs/cli/commands.md
+1 -3
View File
@@ -554,9 +554,7 @@ Options:
Scope: `root`
Validate `@backstage` dependencies within the repo, making sure that there are
no duplicates of packages that might lead to breakages. For example,
`@backstage/core` must not be loaded in twice, so having two different versions
of it installed will cause this command to exit with an error.
no duplicates of packages that might lead to breakages.
By supplying the `--fix` flag the command will attempt to fix any conflict that
can be resolved by editing `yarn.lock`, but will not attempt to search for
docs/conf/reading.md
+2 -2
View File
@@ -112,7 +112,7 @@ example `getString`. These will throw an error if there is no value available.
The [ConfigApi](../reference/utility-apis/Config.md) in the frontend is a
[UtilityApi](../api/utility-apis.md). It's accessible as usual via the
`configApiRef` exported from `@backstage/core`.
`configApiRef` exported from `@backstage/core-plugin-api`.
Depending on the config api in another API is slightly different though, as the
`ConfigApi` implementation is supplied via the App itself and not instantiated
@@ -123,7 +123,7 @@ for an example of how this wiring is done.
For standalone plugin setups in `dev/index.ts`, register a factory with a
statically mocked implementation of the config API. Use the `ConfigReader` from
`@backstage/config` to create an instance and register it for the `configApiRef`
from `@backstage/core`.
from `@backstage/core-plugin-api`.
## Accessing ConfigApi in Backend Plugins
docs/deployment/docker.md
+4 -3
View File
@@ -59,16 +59,17 @@ Once the host build is complete, we are ready to build our image. The following
FROM node:14-buster-slim
WORKDIR /app
# Copy repo skeleton first, to avoid unnecessary docker cache invalidation.
# The skeleton contains the package.json of each package in the monorepo,
# and along with yarn.lock and the root package.json, that's enough to run yarn install.
ADD yarn.lock package.json packages/backend/dist/skeleton.tar.gz ./
COPY yarn.lock package.json packages/backend/dist/skeleton.tar.gz ./
RUN tar xzf skeleton.tar.gz && rm skeleton.tar.gz
RUN yarn install --frozen-lockfile --production --network-timeout 300000 && rm -rf "$(yarn cache dir)"
# Then copy the rest of the backend bundle, along with any other files we might want.
ADD packages/backend/dist/bundle.tar.gz app-config.yaml ./
COPY packages/backend/dist/bundle.tar.gz app-config.yaml ./
RUN tar xzf bundle.tar.gz && rm bundle.tar.gz
CMD ["node", "packages/backend", "--config", "app-config.yaml"]
```
docs/dls/contributing-to-storybook.md
+1 -1
View File
@@ -25,7 +25,7 @@ component, which are then displayed both visually and with sample code to be
copied.
When custom Backstage components are created, they are placed in the
`@backstage/core` package and added to the Storybook.
`@backstage/core-components` package and added to the Storybook.
There may be times where an existing Material-UI component (in
`@material-ui/core`) is sufficient and doesn't need to be wrapped or duplicated.
docs/features/kubernetes/configuration.md
+2 -2
View File
@@ -68,7 +68,7 @@ The base URL to the Kubernetes control plane. Can be found by using the
##### `clusters.\*.name`
A name to represent this cluster, this must be unique within the `clusters`
array. Users will see this value in the Service Catalog Kubernetes plugin.
array. Users will see this value in the Software Catalog Kubernetes plugin.
##### `clusters.\*.authProvider`
@@ -195,7 +195,7 @@ annotations:
#### Labeling Kubernetes components
In order for Kubernetes components to show up in the service catalog as a part
In order for Kubernetes components to show up in the software catalog as a part
of an entity, Kubernetes components themselves can have the following label:
```yaml
docs/features/kubernetes/index.md
+1 -1
View File
@@ -2,7 +2,7 @@
id: overview
title: Kubernetes
sidebar_label: Overview
description: Monitoring Kubernetes based services with the service catalog
description: Monitoring Kubernetes based services with the software catalog
---
Kubernetes in Backstage is a tool that's designed around the needs of service
docs/features/search/getting-started.md
+1 -1
View File
@@ -29,7 +29,7 @@ Backstage app with the following contents:
```tsx
import React from 'react';
import { Content, Header, Page } from '@backstage/core';
import { Content, Header, Page } from '@backstage/core-components';
import { Grid, List, Card, CardContent } from '@material-ui/core';
import {
SearchBar,
docs/features/software-catalog/index.md
+12 -12
View File
@@ -1,29 +1,29 @@
---
id: software-catalog-overview
title: Backstage Service Catalog (alpha)
title: Backstage Software Catalog (alpha)
sidebar_label: Overview
# prettier-ignore
description: The Backstage Service Catalog — actually, a software catalog, since it includes more than just services
description: The Backstage Software Catalog
---
## What is a Service Catalog?
## What is a Software Catalog?
The Backstage Service Catalog — actually, a software catalog, since it includes
The Backstage Software Catalog — actually, a software catalog, since it includes
more than just services — is a centralized system that keeps track of ownership
and metadata for all the software in your ecosystem (services, websites,
libraries, data pipelines, etc). The catalog is built around the concept of
[metadata YAML files](descriptor-format.md) stored together with the code, which
are then harvested and visualized in Backstage.
![service-catalog](https://backstage.io/blog/assets/6/header.png)
![software-catalog](https://backstage.io/blog/assets/6/header.png)
## How it works
Backstage and the Backstage Service Catalog make it easy for one team to manage
Backstage and the Backstage Software Catalog make it easy for one team to manage
10 services — and makes it possible for your company to manage thousands of
them.
More specifically, the Service Catalog enables two main use-cases:
More specifically, the Software Catalog enables two main use-cases:
1. Helping teams manage and maintain the software they own. Teams get a uniform
view of all their software; services, libraries, websites, ML models — you
@@ -37,11 +37,11 @@ The Software Catalog is available to browse at `/catalog`. If you've followed
[Getting Started with Backstage](../../getting-started), you should be able to
browse the catalog at `http://localhost:3000`.
![](../../assets/software-catalog/service-catalog-home.png)
![](../../assets/software-catalog/software-catalog-home.png)
## Adding components to the catalog
The source of truth for the components in your service catalog are
The source of truth for the components in your software catalog are
[metadata YAML files](descriptor-format.md) stored in source control (GitHub,
GitHub Enterprise, GitLab, ...).
@@ -104,11 +104,11 @@ them, and do so using their normal Git workflow.
![](../../assets/software-catalog/bsc-edit.png)
Once the change has been merged, Backstage will automatically show the updated
metadata in the service catalog after a short while.
metadata in the software catalog after a short while.
## Finding software in the catalog
By default the service catalog shows components owned by the team of the logged
By default the software catalog shows components owned by the team of the logged
in user. But you can also switch to _All_ to see all the components across your
company's software ecosystem. Basic inline _search_ and _column filtering_ makes
it easy to browse a big set of components.
@@ -124,7 +124,7 @@ _starring_ of components:
## Integrated tooling through plugins
The service catalog is a great way to organize the infrastructure tools you use
The software catalog is a great way to organize the infrastructure tools you use
to manage the software. This is how Backstage creates one developer portal for
all your tools. Rather than asking teams to jump between different
infrastructure UIs (and incurring additional cognitive overhead each time they
docs/features/software-templates/adding-templates.md
+1 -1
View File
@@ -83,7 +83,7 @@ spec:
[Template Entity](../software-catalog/descriptor-format.md#kind-template)
contains more information about the required fields.
Once we have a `template.yaml` ready, we can then add it to the service catalog
Once we have a `template.yaml` ready, we can then add it to the software catalog
for use by the scaffolder.
You can add the template files to the catalog through
docs/features/software-templates/writing-templates.md
+2 -2
View File
@@ -4,8 +4,8 @@ title: Writing Templates
description: Details around creating your own custom Software Templates
---
Templates are stored in the **Service Catalog** under a kind `Template`. You can
create your own templates with a small `yaml` definition which describes the
Templates are stored in the **Software Catalog** under a kind `Template`. You
can create your own templates with a small `yaml` definition which describes the
template and it's metadata, along with some input variables that your template
will need, and then a list of actions which are then executed by the scaffolding
service.
docs/features/techdocs/how-to-guides.md
-5
View File
@@ -78,11 +78,6 @@ the repository. The archive does not have any git history attached to it. Also
it is a compressed file. Hence the file size is significantly smaller than how
much data git clone has to transfer.
Caveat: Currently TechDocs sites built using URL Reader will be cached for 30
minutes which means they will not be re-built if new changes are made within 30
minutes. This cache invalidation will be replaced by commit timestamp based
implementation very soon.
## How to use a custom TechDocs home page?
### 1st way: TechDocsCustomHome with a custom configuration
docs/features/techdocs/troubleshooting.md
+17
View File
@@ -55,3 +55,20 @@ INFO - Start watching changes
[I 210115 19:00:45 handlers:64] Start detecting changes
INFO - Start detecting changes
```
## PlantUML with `svg_object` doesn't render
The [plantuml-markdown](https://pypi.org/project/plantuml-markdown/) MkDocs
plugin available in
[`mkdocs-techdocs-core`](https://github.com/backstage/mkdocs-techdocs-core)
supports different formats for rendering diagrams. TechDocs does however not
support all of them.
The `svg_object` format renders a diagram as an HTML `<object>` tag but this is
not allowed as it enables bad actors to inject malicious content into
documentation pages. See
[CVE-2021-32661](https://github.com/advisories/GHSA-gg96-f8wr-p89f) for more
details.
Instead use `svg_inline` which renders as an `<svg>` tag and provides the same
benefits as `svg_object`.
docs/getting-started/app-custom-theme.md
+1 -1
View File
@@ -56,7 +56,7 @@ For example, adding the theme that we created in the previous section can be
done like this:
```ts
import { createApp } from '@backstage/core';
import { createApp } from '@backstage/core-app-api';
const app = createApp({
apis: ...,
docs/getting-started/contributors.md
+1 -1
View File
@@ -94,7 +94,7 @@ here are some useful ones:
```python
yarn start # Start serving the example app, use --check to include type checks and linting
yarn storybook # Start local storybook, useful for working on components in @backstage/core
yarn storybook # Start local storybook, useful for working on components in @backstage/core-components
yarn workspace @backstage/plugin-welcome start # Serve welcome plugin only, also supports --check
docs/getting-started/create-an-app.md
+6 -5
View File
@@ -137,7 +137,7 @@ frontend with `yarn start` in one window, and the backend with
It can often be useful to try out changes to the packages in the main Backstage
repo within your own app. For example if you want to make modifications to
`@backstage/core` and try them out in your app.
`@backstage/core-plugin-api` and try them out in your app.
To link in external packages, add them to your `package.json` and `lerna.json`
workspace paths. These can be either relative or absolute paths with or without
@@ -147,7 +147,7 @@ globs. For example:
"packages": [
"packages/*",
"plugins/*",
"../backstage/packages/core", // New path added to work on @backstage/core
"../backstage/packages/core-plugin-api", // New path added to work on @backstage/core-plugin-api
],
```
@@ -157,9 +157,10 @@ Then reinstall packages to make yarn set up symlinks:
yarn install
```
With this in place you can now modify the `@backstage/core` package within the
main repo, and have those changes be reflected and tested in your app. Simply
run your app using `yarn dev` (or `yarn start` for just frontend) as normal.
With this in place you can now modify the `@backstage/core-plugin-api` package
within the main repo, and have those changes be reflected and tested in your
app. Simply run your app using `yarn dev` (or `yarn start` for just frontend) as
normal.
Note that for backend packages you need to make sure that linked packages are
not dependencies of any non-linked package. If you for example want to work on
docs/getting-started/project-structure.md
+7 -8
View File
@@ -127,18 +127,17 @@ are separated out into their own folder, see further down.
used by the backend, we chose to separate `config` and `config-loader` into
two different packages.
- [`core/`](https://github.com/backstage/backstage/tree/master/packages/core) -
- [`core-app-api/`](https://github.com/backstage/backstage/tree/master/packages/core-app-api) -
This package contains the core APIs that are used to wire together Backstage
apps.
- [`core-components/`](https://github.com/backstage/backstage/tree/master/packages/core-components) -
This package contains our visual React components, some of which you can find
in
[plugin examples](https://backstage.io/storybook/?path=/story/plugins-examples--plugin-with-data).
Apart from that it re-exports everything from [`core-api`] so that users only
need to rely on one package.
- [`core-api/`](https://github.com/backstage/backstage/tree/master/packages/core-api) -
This package contains APIs and definitions of such. It is it's own package
because we needed to split our `test-utils` package. It's an implementation
detail that we try to hide from our users, and no one should have to depend on
it directly.
- [`core-plugin-api/`](https://github.com/backstage/backstage/tree/master/packages/core-plugin-api) -
This package contains the core APIs that are used to build Backstage plugins.
- [`create-app/`](https://github.com/backstage/backstage/tree/master/packages/create-app) -
An CLI to specifically scaffold a new Backstage App. It does so by using a
docs/integrations/ldap/org.md
+16 -10
View File
@@ -14,19 +14,25 @@ entities that mirror your org setup.
## Installation
The processor that performs the import, `LdapOrgReaderProcessor`, comes
installed with the default setup of Backstage.
1. The processor is not installed by default, therefore you have to add a
dependency to `@backstage/plugin-catalog-backend-module-ldap` to your backend
package.
If you replace the set of processors in your installation using that facility of
the catalog builder class, you can import and add it as follows.
```bash
# From your Backstage root directory
cd packages/backend
yarn add @backstage/plugin-catalog-backend-module-ldap
```
```ts
// Typically in packages/backend/src/plugins/catalog.ts
import { LdapOrgReaderProcessor } from '@backstage/plugin-catalog-backend';
2. The `LdapOrgReaderProcessor` is not registered by default, so you have to
register it in the catalog plugin:
builder.replaceProcessors(
LdapOrgReaderProcessor.fromConfig(config, { logger }),
// ...
```typescript
// packages/backend/src/plugins/catalog.ts
builder.addProcessor(
LdapOrgReaderProcessor.fromConfig(config, {
logger,
}),
);
```
docs/overview/architecture-overview.md
+2 -2
View File
@@ -25,7 +25,7 @@ different ways.
The following diagram shows how Backstage might look when deployed inside a
company which uses the Tech Radar plugin, the Lighthouse plugin, the CircleCI
plugin and the service catalog.
plugin and the software catalog.
There are 3 main components in this architecture:
@@ -142,7 +142,7 @@ Its architecture looks like this:
![lighthouse plugin backed to microservice and database](../assets/architecture-overview/lighthouse-plugin-architecture.png)
The service catalog in Backstage is another example of a service backed plugin.
The software catalog in Backstage is another example of a service backed plugin.
It retrieves a list of services, or "entities", from the Backstage Backend
service and renders them in a table for the user.
docs/overview/background.md
+2 -2
View File
@@ -22,8 +22,8 @@ Our idea was to centralize and simplify end-to-end software development with an
abstraction layer that sits on top of all of our infrastructure and developer
tooling. That’s Backstage.
It’s a developer portal powered by a centralized service catalog — with a plugin
architecture that makes it endlessly extensible and customizable.
It’s a developer portal powered by a centralized software catalog — with a
plugin architecture that makes it endlessly extensible and customizable.
Manage all your services, software, tooling, and testing in Backstage. Start
building a new microservice using an automated template in Backstage. Create,
docs/overview/roadmap.md
+3 -3
View File
@@ -22,7 +22,7 @@ We have divided the project into three high-level _phases_:
[UX patterns and components](https://backstage.io/storybook) help ensure a
consistent experience between tools.
- 🐢 **Phase 2:** Service Catalog
- 🐢 **Phase 2:** Software Catalog
([alpha released](https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha)) -
With a single catalog, Backstage makes it easy for a team to manage ten
services — and makes it possible for your company to manage thousands of them.
@@ -120,13 +120,13 @@ Chances are that someone will jump in and help build it.
- [TechDocs v1](https://backstage.io/blog/2020/09/08/announcing-tech-docs)
- [Plugin marketplace](https://backstage.io/plugins)
- [Improved and move documentation to backstage.io](https://backstage.io/docs/overview/what-is-backstage)
- [Backstage Service Catalog (alpha)](https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha)
- [Backstage Software Catalog (alpha)](https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha)
- [Backstage Software Templates (alpha)](https://backstage.io/blog/2020/08/05/announcing-backstage-software-templates)
- [Make it possible to add custom auth providers](https://backstage.io/blog/2020/07/01/how-to-enable-authentication-in-backstage-using-passport)
- [TechDocs v0](https://github.com/backstage/backstage/milestone/15)
- CI plugins: CircleCI, Jenkins, GitHub Actions and TravisCI
- [Service API documentation](https://github.com/backstage/backstage/pull/1737)
- Backstage Service Catalog can read from: GitHub, GitLab,
- Backstage Software Catalog can read from: GitHub, GitLab,
[Bitbucket](https://github.com/backstage/backstage/pull/1938)
- Support auth providers: Google, Okta, GitHub, GitLab,
[auth0](https://github.com/backstage/backstage/pull/1611),
docs/overview/stability-index.md
+3 -15
View File
@@ -106,16 +106,6 @@ Used to load in static configuration, mainly for use by the CLI and
Stability: `1`. Mainly intended for internal use.
### `core` [GitHub](https://github.com/backstage/backstage/tree/master/packages/core/)
The `@backstage/core` and `@backstage/core-api` packages are being phased out
and replaced by other `@backstage/core-*` packages. They are still in use but
will not receive any breaking changes.
### `core-api` [GitHub](https://github.com/backstage/backstage/tree/master/packages/core-api/)
Stability: See `@backstage/core` above
### `core-app-api` [GitHub](https://github.com/backstage/backstage/tree/master/packages/core-app-api/)
The APIs used exclusively in the app, such as `createApp` and the system icons.
@@ -194,8 +184,9 @@ Stability: `2`
### `test-utils-core` [GitHub](https://github.com/backstage/backstage/tree/master/packages/test-utils-core/)
Internal testing utilities that are separated out for usage in
@backstage/core-api. All exports are re-exported by @backstage/test-utils. This
package should not be depended on directly.
@backstage/core-app-api and @backstage/core-plugin-api. All exports are
re-exported by @backstage/test-utils. This package should not be depended on
directly.
Stability: See @backstage/test-utils
@@ -218,9 +209,6 @@ Stability: `1`
## Plugins
Plugins are rarely marked as stable as the `@backstage/core` plugin API is under
heavy development.
Many backend plugins are split into "REST API" and "TypeScript Interface"
sections. The "TypeScript Interface" refers to the API used to integrate the
plugin into the backend.
docs/overview/what-is-backstage.md
+4 -4
View File
@@ -2,13 +2,13 @@
id: what-is-backstage
title: What is Backstage?
# prettier-ignore
description: Backstage is an open platform for building developer portals. Powered by a centralized service catalog, Backstage restores order to your microservices and infrastructure
description: Backstage is an open platform for building developer portals. Powered by a centralized software catalog, Backstage restores order to your microservices and infrastructure
---
![service-catalog](https://backstage.io/blog/assets/6/header.png)
![software-catalog](https://backstage.io/blog/assets/6/header.png)
[Backstage](https://backstage.io/) is an open platform for building developer
portals. Powered by a centralized service catalog, Backstage restores order to
portals. Powered by a centralized software catalog, Backstage restores order to
your microservices and infrastructure and enables your product teams to ship
high-quality code quickly — without compromising autonomy.
@@ -17,7 +17,7 @@ to create a streamlined development environment from end to end.
Out of the box, Backstage includes:
- [Backstage Service Catalog](../features/software-catalog/index.md) for
- [Backstage Software Catalog](../features/software-catalog/index.md) for
managing all your software (microservices, libraries, data pipelines,
websites, ML models, etc.)
docs/plugins/composability.md
+5 -4
View File
@@ -511,10 +511,11 @@ clarify intent. Refer to the following table to formulate the new name:
## Porting Existing Apps
The first step of porting any app is to replace the root `Routes` component with
`FlatRoutes` from `@backstage/core`. As opposed to the `Routes` component,
`FlatRoutes` only considers the first level of `Route` components in its
children, and provides any additional children to the outlet of the route. It
also removes the need to append `"/*"` to paths, as it is added automatically.
`FlatRoutes` from `@backstage/core-app-api`. As opposed to the `Routes`
component, `FlatRoutes` only considers the first level of `Route` components in
its children, and provides any additional children to the outlet of the route.
It also removes the need to append `"/*"` to paths, as it is added
automatically.
```diff
const AppRoutes = () => (
docs/plugins/index.md
+4 -4
View File
@@ -28,9 +28,9 @@ This helps the community know what plugins are in development.
You can also use this process if you have an idea for a good plugin but you hope
that someone else will pick up the work.
## Integrate into the Service Catalog
## Integrate into the Software Catalog
If your plugin isn't supposed to live as a standalone page, but rather needs to
be presented as a part of a Service Catalog (e.g. a separate tab or a card on an
"Overview" tab), then check out
[the instruction](integrating-plugin-into-service-catalog.md) on how to do it.
be presented as a part of a Software Catalog (e.g. a separate tab or a card on
an "Overview" tab), then check out
[the instruction](integrating-plugin-into-software-catalog.md) on how to do it.
docs/plugins/integrating-plugin-into-service-catalog.md → docs/plugins/integrating-plugin-into-software-catalog.md
+3 -3
View File
@@ -1,7 +1,7 @@
---
id: integrating-plugin-into-service-catalog
title: Integrate into the Service Catalog
description: How to integrate a plugin into service catalog
id: integrating-plugin-into-software-catalog
title: Integrate into the Software Catalog
description: How to integrate a plugin into software catalog
---
> This is an advanced use case and currently is an experimental feature. Expect
docs/plugins/plugin-development.md
+3 -3
View File
@@ -36,7 +36,7 @@ to avoid import cycles, for example like this:
```tsx
/* src/routes.ts */
import { createRouteRef } from '@backstage/core';
import { createRouteRef } from '@backstage/core-plugin-api';
// Note: This route ref is for internal use only, don't export it from the plugin
export const rootRouteRef = createRouteRef({
@@ -46,11 +46,11 @@ export const rootRouteRef = createRouteRef({
Now that we have a `RouteRef`, we import it into `src/plugin.ts`, create our
plugin instance with `createPlugin`, as well as create and wrap our routable
extension using `createRoutableExtension` from `@backstage/core`:
extension using `createRoutableExtension` from `@backstage/core-plugin-api`:
```tsx
/* src/plugin.ts */
import { createPlugin, createRouteRef } from '@backstage/core';
import { createPlugin, createRouteRef } from '@backstage/core-plugin-api';
import ExampleComponent from './components/ExampleComponent';
// Create a plugin instance and export this from your plugin package
docs/plugins/structure-of-a-plugin.md
+4 -1
View File
@@ -57,7 +57,10 @@ package.json to declare the plugin dependencies, metadata and scripts.
In the `src` folder we get to the interesting bits. Check out the `plugin.ts`:
```jsx
import { createPlugin, createRoutableExtension } from '@backstage/core';
import {
createPlugin,
createRoutableExtension,
} from '@backstage/core-plugin-api';
import { rootRouteRef } from './routes';
docs/reference/createPlugin-feature-flags.md
+2 -2
View File
@@ -11,7 +11,7 @@ can use this to split out logic in your code for manual A/B testing, etc.
Here's a code sample:
```typescript
import { createPlugin } from '@backstage/core';
import { createPlugin } from '@backstage/core-plugin-api';
export default createPlugin({
id: 'plugin-name',
@@ -29,7 +29,7 @@ To inspect the state of a feature flag inside your plugin, you can use the
```tsx
import React from 'react';
import { Button } from '@material-ui/core';
import { featureFlagsApiRef, useApi } from '@backstage/core';
import { featureFlagsApiRef, useApi } from '@backstage/core-plugin-api';
const ExamplePage = () => {
const featureFlags = useApi(featureFlagsApiRef);
docs/reference/createPlugin.md
+1 -1
View File
@@ -30,7 +30,7 @@ type PluginHooks = {
Showcasing adding a feature flag.
```jsx
import { createPlugin } from '@backstage/core';
import { createPlugin } from '@backstage/core-plugin-api';
export default createPlugin({
id: 'new-plugin',
docs/tutorials/journey.md
+5 -5
View File
@@ -55,10 +55,10 @@ const spotifyAuthApiRef = createApiRef<OAuthApi>({
Sam realizes that Spotify auth might be useful to others, and that it would be
more convenient if it was a part of the Backstage Core. After submitting and
merging a Pull Request with the additions to the
`@backstage/plugin-auth-backend` and `@backstage/core` packages, Spotify auth is
now available for everyone to use. Since the Backstage Core team also adds it to
the public demo server, Sam can now get rid of it in the local setup and rely on
the shared development auth providers instead.
`@backstage/plugin-auth-backend` and `@backstage/core-plugin-api` packages,
Spotify auth is now available for everyone to use. Since the Backstage Core team
also adds it to the public demo server, Sam can now get rid of it in the local
setup and rely on the shared development auth providers instead.
The only thing left now is making sure that users of the plugin provide Spotify
auth in the app. Sam ensures this by adding `spotifyAuthApiRef` to the plugin's
@@ -70,7 +70,7 @@ README.
This plugin requires the following APIs to function:
- `spotifyAuthApiRef` from `@backstage/core@^1.1.0`
- `spotifyAuthApiRef` from `@@backstage/core-plugin-api@^1.1.0`
```
# 3. The Catalog Awakens
docs/tutorials/migrating-away-from-core.md
+135
View File
@@ -0,0 +1,135 @@
---
id: migrating-away-from-core
title: Migrating away from @backstage/core
description: Guide on how to migrate to the new Backstage core libraries.
---
The `@backstage/core` package has been split into three separate packages,
`@backstage/core-app-api`, `@backstage/core-plugin-api`, and
`@backstage/core-components`. For more information about the reasoning behind
this change and the naming of the packages, see the
[original RFC](https://github.com/backstage/backstage/issues/4872) and
[initial PR](https://github.com/backstage/backstage/pull/5825).
The main purpose of the split is to make plugins more decoupled from the app,
and open up for the possibility of combining plugins using many different
versions of the core libraries. This should significantly reduce the maintenance
burden on plugin authors, as well as reduce the impact of breaking changes in
the core APIs.
## Migration
At a high level the migration is done by simply replacing usages of
`@backstage/core` with one or more of the three new core libraries. There are a
few breaking changes in the new packages that are listed below, but for most
plugins the migration is a simple replacement. In order to make the migration as
smooth as possible we provide a collection of tools to automate the majority of
the migration effort.
Below is a list of steps that should get most projects completely migrated, the
order of the steps is a recommendation but not required, so don't worry if you
need to go back to previous steps to fix things.
### Step 1 - Run codemod
The first step is to run
[`@backstage/codemods`](https://www.npmjs.com/package/@backstage/codemods)
across your project. This will automatically convert all module imports in your
source code to use one of the three new core packages instead. For example, the
following change might occur:
```diff
-import { useApi, configApiRef, InfoCard } from '@backstage/core';
+import { useApi, configApiRef } from '@backstage/core-plugin-api';
+import { InfoCard } from '@backstage/core-components';
```
In a typical app created with `@backstage/create-app`, you would run the
following:
```shell
npx @backstage/codemods apply core-imports packages plugins
```
The last two arguments, `packages` and `plugins`, are the folders that the
codemod should be applied to. Add or remove folders as needed for your project.
The codemod might fail for some files because of the missing `IconKey` type in
any of the new packages. This is one of the few breaking changes. To fix, remove
any `IconKey` imports and replace usages of it with the `string` type, see the
breaking changes section below for details. Once usages of `IconKey` type have
been removed, you can re-run the codemod for those files.
Note that while the codemod tries to stick to using the existing formatting in
your project, it doesn't always manage to do that. If you're using `prettier` to
format the code in your project, it's best to run `prettier --write` on any
files that were changed by the codemod.
### Step 2 - Update dependencies
The next step is to update dependencies in your `package.json` files. Any
package that currently depends on `@backstage/core` will need to have it
replaced by one or more of the new packages. The app package should have all
three packages added to `dependencies`, while for plugins and additional non-app
packages, the `@backstage/core-plugin-api` and `@backstage/core-components`
packages should be added to the set of regular `dependencies`, and
`@backstage/core-app-api` should be added to `devDependencies` for usage in
tests.
A tool that can help out with step is the `plugin:diff` command from the
`@backstage/cli`, it will compare your plugin to the base plugin template and
suggest changes where the plugin deviates. A quick way to get this step done if
you have up-to-date project is to run the following in the project root:
```bash
# The --yes flag causes all suggested changes to be accepted automatically
yarn diff --yes
```
If you do not have the `diff` command set up in `package.json`, you can also
manually execute the following in each plugin folder:
```bash
yarn backstage-cli plugin:diff --yes
```
### Step 3 - Manual review
At this point your app is either completely or very close to being migrated. Run
type checks with `yarn tsc` to check if you hit any of the breaking changes
below or if there are any other things to fix. It can also be worthwhile
searching for occurrences of `@backstage/core` in the codebase, as that might
find usages in for example `jest` mock calls, which aren't handled by the
codemod.
As a final step you'll want to boot up the app and take it through any regular
verification step that you have set up for your project. Don't hesitate to open
a GitHub issue, PR, or reach out on Discord if you hit any snags, or if there
are any additional steps or hints that you think should be added to this guide!
## Breaking Changes
The following is a list of breaking changes between `@backstage/core` and the
three new core packages. Not that this list may not be exhaustive depending on
when you migrate your app, as new releases of the new core packages may bring
further changes.
### Removed `IconKey` type
The `IconKey` type used to be a string union of all known keys used for the app
icons available through `useApp().getSystemIcon(key)`. The type has been removed
since the set of allowed icon keys is no longer constrained, and there is
instead only a guarantee that the app provides a minimum set of icons, but can
provide any icons it wants beyond that. Migration is done by simply replacing
old usages by the `string` type.
### Constrained `IconComponent` type
The `IconComponent` type used to allow all of the props from the MUI `SvgIcon`.
This encouraged some bad patterns in open source plugins such as applying colors
to the icons, which in turn hurt the ability to replace the icons with custom
ones. The `IconComponent` type, which is now exported from
`@backstage/core-plugin-api`, now only accepts a `fontSize` prop used to set the
size of the icon. The type is compatible with the MUI `SvgIcon`, but there may
be situations where an icon needs an explicit cast to `IconComponent` in order
to narrow the type.
docs/tutorials/quickstart-app-plugin.md
+3 -8
View File
@@ -72,7 +72,7 @@ Our first modification will be to extract information from the Identity API.
```tsx
// Add identityApiRef to the list of imported from core
import { identityApiRef, useApi } from '@backstage/core';
import { identityApiRef, useApi } from '@backstage/core-plugin-api';
```
3. Adjust the ExampleComponent from inline to block
@@ -137,13 +137,8 @@ changes, let's start by wiping this component clean.
import React from 'react';
import { useAsync } from 'react-use';
import Alert from '@material-ui/lab/Alert';
import {
Table,
TableColumn,
Progress,
githubAuthApiRef,
useApi,
} from '@backstage/core';
import { Table, TableColumn, Progress } from '@backstage/core-components';
import { githubAuthApiRef, useApi } from '@backstage/core-plugin-api';
import { graphql } from '@octokit/graphql';
export const ExampleFetchComponent = () => {
microsite/blog/2021-06-22-spotify-backstage-is-growing.md
+75
View File
@@ -0,0 +1,75 @@
---
title: How Spotify is helping more companies adopt Backstage
author: Austin Lamon, Spotify
authorURL: https://www.linkedin.com/in/austinlamon
---
[![The Backstage community is growing! In just over a year, Backstage has gone from a few open source building blocks to a thriving platform used by engineering orgs with thousands of developers. But even with 30+ adopting companies and 400+ contributors, we are still in the very early stages of reaching the platform’s potential.](assets/21-06-22/spotify-backstage-header.gif)](https://backstage.spotify.com/)
_[backstage.spotify.com](https://backstage.spotify.com)_
The Backstage community is growing! In just over [a year](https://engineering.atspotify.com/2021/03/16/happy-birthday-backstage-spotifys-biggest-open-source-project-grows-up-fast/), Backstage has gone from a few open source building blocks to a thriving platform used by engineering orgs with thousands of developers. But even with 30+ [adopting companies](https://github.com/backstage/backstage/blob/master/ADOPTERS.md) and 400+ contributors, we are still in the very early stages of reaching the platform’s potential.
In order to grow Backstage further, Spotify is increasing the support we provide both adopters (the people integrating Backstage into their organizations) and contributors (the people building features and improving the code). The more companies that adopt Backstage, the more support the project gets, the stronger the platform becomes for everyone.
And while Spotify remains committed to maturing the Backstage platform — both as original creator and active maintainer — we also want to make room for the community to take greater ownership. Backstage may have started inside Spotify, but it belongs to all of you. So, we hope you join us in what’s next.
<!--truncate-->
## What’s next: More support for adopters and contributors
Alongside the code contributions, technical support, and community leadership provided by our dedicated (and still growing) Backstage team, Spotify is introducing three additional ways to help lower the barriers to adopting the platform:
1. **New consulting support.** In addition to investing in the Backstage getting started experience and the technical support we already provide, we’re adding [consulting support](https://backstage.spotify.com) for companies who are looking to adopt (or are already in the middle of adopting) Backstage.
2. **Double the community sessions.** We are creating separate meetups for Backstage adopters and Backstage contributors for more focused discussions. (Come to both!)
3. **Adding reviewers and maintainers.** We recently introduced [reviewers](https://github.com/backstage/backstage/pull/5137) to the Backstage project to speed up PR reviews and approvals, with the hope of also adding more maintainers in the future.
## Why Spotify is increasing its investment in open source (and why now)
Before we talk in more detail about these new efforts, why is Spotify doing this? The short answer is the same answer as when we released the very first open source version of Backstage: we envision Backstage as the standard developer portal platform across the industry.
### Setting the standard, both inside and outside Spotify
We believe in Backstage — we believe in the developer experience it provides, the developer-centric culture it encourages, and the immense value that the open source community brings to it. It is no exaggeration to say that we depend on Backstage every day at Spotify. It’s the central hub for our internal R&D community, and it’s both mission-critical to our daily operations and our future growth.
### We’re an adopter, too
We (that includes Spotify’s leadership, as well as our platform teams and dedicated Backstage team) also believe that Backstage’s continued success here — inside Spotify — depends on its success out here — in the wider open source community, where Backstage can reach its full potential. Like other adopters, we’re fully invested in the platform’s growth.
### An open platform is the strongest platform
We genuinely believe that the best platform for developers can only be shaped by the most diverse group of developers. Each new adopter and every new contributor brings unique perspectives and experiences to the challenges of improving developer experience and effectiveness. As the project scales — and progresses toward CNCF graduation — we need to make more room in the community for both adopters and contributors.
So, let’s get to it.
## Consulting support (and a new website) for adopters
[![Who else is using Backstage? Netflix, Zalando, TELUS, DoorDash, more](assets/21-06-22/spotify-backstage-adopters.png)](https://backstage.spotify.com/)
We’ve launched a new website at: [backstage.spotify.com](https://backstage.spotify.com). It’s a hub for new and potential adopters to receive support from Spotify and our Preferred Partners. The site is focused on helping organizations get up and running with Backstage by addressing their unique needs and use cases.
You’ll find a high-level introduction to the platform, tips and tricks tested by Spotify to accelerate developer effectiveness, and access to a group of partners that have scaled Backstage for numerous adopters. You can also use the site to book product overviews, demos, and technical deep dives with members of the Spotify team.
We will continue to post important product announcements, technical documentation, feature demos, and community news here on Backstage.io. ([Subscribe to the newsletter](https://mailchi.mp/spotify/backstage-community) to stay up to date.) And both contributors and adopting companies can continue to find around-the-clock/around-the-world technical support on [GitHub](https://github.com/backstage/backstage) and [Discord](https://discord.gg/MUpMjP2).
## Separate community sessions for adopters and contributors
[![Backstage Community Sessions, hosted by Spotify](assets/21-06-22/backstage-community-sessions.png)](https://github.com/backstage/community/#backstage-community)
Earlier this year, we began hosting [Backstage Community Sessions](https://github.com/backstage/community/#backstage-community) — official meetups for anyone who wanted to join them. Since [the very first one](https://youtu.be/4-VX9tDdJYY), the Backstage team has been inspired and humbled by the community’s participation in these sessions — from hearing the [Expedia Group team share their journey adopting Backstage](https://youtu.be/rRphwXeq33Q?t=1509) to discussions about TypeScript and Material-UI. It’s great collaborating through code — but it’s also a lot of fun when you can see each other’s faces and have a conversation.
And while these sessions have been a success, the feedback we’ve gotten from the community has been very clear: more frequent and more focused conversations. So, later this summer, we’ll be launching standalone Backstage Adopter Sessions and Backstage Contributor Sessions. We hope this will lead to more useful sessions for everyone — and, of course, you are welcome to attend either or both:
- **For the adopter sessions:** we invite you to share the challenges, learnings, and use cases you’re facing with companies similar to yourselves.
- **For the contributor sessions:** we invite you to share thoughts, suggestions, and gaps in the Backstage core with the maintainers and reviewers.
Speaking of reviewers and maintainers…
## Adding reviewers and maintainers
[![GitHub logo](assets/21-06-22/gh-reviewers.png)](https://github.com/backstage/backstage/blob/master/GOVERNANCE.md#reviewers)
We have introduced [reviewers](https://github.com/backstage/backstage/blob/master/GOVERNANCE.md#reviewers) to the project! By adding this new role, we’ve expanded the number of people who are permitted to approve and merge pull requests. This will offload some of the review work from the maintainers, simplifying and speeding up the review process for contributors.
Of course, with these new efforts, we expect even more companies to adopt Backstage, which means the platform will continue to grow, and the number of PRs will continue to grow with it. As that happens, we hope to add to both the maintainer and reviewer teams in the future.
So, I’ll end this post as it began: the Backstage community is growing! And we look forward to growing even bigger, even faster, together.
microsite/blog/2021-06-24-announcing-backstage-search-platform.md
+101
View File
@@ -0,0 +1,101 @@
---
title: Announcing the Backstage Search platform: a customizable search tool built just for you
author: Emma Indal, Spotify
authorURL: https://www.linkedin.com/in/emma-indal
---
![Backstage Search platform](assets/21-06-24/backstage-search-platform.png)
**TLDR;** The new Backstage Search is now available in alpha, ready for you to start building on. A total rethinking of the core search feature in Backstage, it’s more than just a box you type into — it’s a mini platform all by itself. With its composable frontend and extensible backend, you can design and build the search tool that suits your organization’s needs.
So, you don’t just get an improved out-of-the-box experience for searching whatever is in your software catalog. You can also add support for searching other sources, too. Customize it the way you want and you can search your catalog, your plugins and docs — and even external sources, like Stack Overflow and Confluence — all at once, all right inside Backstage.
With one query, your teams can find exactly what they’re looking for: anything and everything.
<!--truncate-->
## Search and explore
Being able to easily explore your ecosystem — to discover software, tools, documentation, and other valuable knowledge — is one of [the three main jobs of Backstage](https://backstage.io/blog/2021/05/20/adopting-backstage#three-jobs-create-manage-explore). Teams should be able to find what other teams have already built, so they can reuse and contribute to components instead of unknowingly duplicating them. Data endpoints should be shared, not siloed away. Services and their APIs should be easily discoverable. Best practices and technical documentation should be easily found.
Along with the [Backstage Service Catalog](https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha), Backstage Search is essential to enabling this discoverability — allowing new hires and old hands alike to explore your infrastructure instead of getting lost inside it.
We also quickly realized that search looks different from organization to organization. Therefore, we built a search platform that lets you plug in your own search engine, index any information you like, or build a customized search page experience that fits your users’ needs.
Since finding what you are looking for in Backstage is critical for success, we started by identifying the needs and goals of search.
## Rethinking search, inside and out
Spotify’s internal version of Backstage has had some of the features of Backstage Search for a while, and open sourcing them has been top of mind since day one. But we didn’t want to just port our internal version to the open source version. We wanted to take the opportunity to apply what we’ve learned inside Spotify over the last year, address the needs we’ve observed in the community, and ultimately open source not just a search feature but a search platform. We started the process by looking at the [jobs to be done](https://hbr.org/2016/09/know-your-customers-jobs-to-be-done).
![Backstage Search platform](assets/21-06-24/jobs-to-be-done.png)
_A high-level overview of the process, identifying all the jobs of search._
First, we looked at which jobs to be done belonged to the search plugin itself (e.g., “collect documents to index”) and which belonged to the other plugins (e.g., “format documents for indexing”), and then whether those jobs belonged to the frontend (“display results”) or the backend (“schedule indexing”).
Looking at all these various jobs, we defined four goals for the platform:
- **Flexibility:** Be search engine–agnostic
- **Simplicity:** Make it easy for content owners to make their content searchable/discoverable
- **Control:** Allow plugin developers to customize their search results components
- **Reusability:** Offer reusable components/APIs that other devs can leverage
Beginning our journey this way — by identifying the jobs to be done first, then defining the product goals from there — we could make sure that the search platform addressed real needs and improved the search experience for both users and plugin developers.
This approach not only created a better search tool for the open source community, but for Spotify, as well. So, instead of just open sourcing our internal version of search, we ended up with an even better solution — one that we can all use and build on together, both inside and outside Spotify.
## Say hello to the Backstage Search platform
![Backstage Search platform](assets/21-06-24/search-results.png)
We are now happy and proud to announce our alpha version of the [Backstage Search Platform](https://backstage.io/docs/features/search/architecture), featuring:
- Bring your own search engine (Flexibility)
- Collators for easily indexing content from plugins and other sources (Simplicity)
- Composable search page experiences (Control, Reusability)
- Customize the look and feel of each search result (Control, Reusability)
### Bring your own search engine
By introducing a Search Integration Layer, we have been able to keep the query translation of the search term and filters close to the search engine itself. This makes our search backend less focused on how a set of terms and filters should be translated to fit a certain search engine interface and more focused on querying and retrieving results as well as collecting results to index.
With the Search Integration Layer, your organization can bring your search engine of choice to Backstage — instead of relying on Backstage to support a specific search engine that might not fit the needs of your organization, either today or in the future.
But that doesn’t mean “batteries not included”. The current version of Backstage Search ships with Lunr support built-in — and support for ElasticSearch is not very far off. And we hope the number of supported search engines will continue to grow with the community’s help.
### Collators for easily indexing content from plugins and other sources
Since Backstage’s functionality comes from its plugins, we wanted the process of making plugin content searchable to be as frictionless as possible. Therefore we decided on a concept we call collators. Collators are responsible for collecting documents to index from a plugin. Your collators live inside your own plugin, but are registered in the Backstage app’s search backend.
Collators can also be used to index external sources, like Stack Overflow and Confluence. You can watch a demo of how easy it is to extend search with collators [here](https://youtu.be/Z78FFaObTfk?t=339).
### Composable search page experiences
Every engineering org has different needs — that is something we have definitely learned over the last year. Your software catalog might be set up differently than ours and therefore your needs for how search results look and how the search filters work will also differ.
That's why we have put effort into making your search page experience composable to your organization's needs. What do we mean by that? When you adopt Backstage and set up your app, you can set up — or, compose — your search page by using existing components or by creating your own custom ones.
### Customize the look and feel of each search result
A good example of the level of customization the platform allows is how list items are displayed in search results. A search result component can be a list, this list can consist of different list items (search results returned from the search engine) — but these list items could look different depending on what the search result returns in terms of its fields.
Let’s say that for an entity returned from the software catalog maybe the most important information to show is the name, while a result returned from the TechDocs plugin should maybe show the text content as the most important information. This can be customized by creating <CustomResultListItem /> components (like TechDocsResultListItem or CatalogResultListItem or whatever list item component you want) and configuring them in the app.
If there is no need to customize your search result list items, the <DefaultResultListItem /> component is there for you to reuse.
## Getting started with Backstage Search
We put together [a getting started guide](https://backstage.io/docs/features/search/getting-started) that provides two different ways to set up Backstage Search:
- Create a new app and get the most out of the search setup right out of the box, or
- Add the new Backstage Search setup to your existing Backstage app.
Whichever situation you’re in, we have you covered.
## What’s next?
We’ve built the foundation for the Backstage Search platform, and we can't wait to see the exciting engines, collators, and components the community builds on the platform.
You can check out our [project roadmap](https://backstage.io/docs/features/search/search-overview#project-roadmap) in our search documentation or track the progress of our [Beta milestone](https://github.com/backstage/backstage/milestone/27) and [GA milestone](https://github.com/backstage/backstage/milestone/28).
For any questions, feedback or ideas about the Backstage Search platform, join us in the #search channel on [Discord](https://discord.gg/MUpMjP2)!
microsite/blog/assets/21-06-22/backstage-community-sessions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB

microsite/blog/assets/21-06-22/gh-reviewers.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 97 KiB

microsite/blog/assets/21-06-22/spotify-backstage-adopters.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 562 KiB

microsite/blog/assets/21-06-22/spotify-backstage-header.gif
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.8 MiB

microsite/blog/assets/21-06-24/backstage-search-platform.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 131 KiB

microsite/blog/assets/21-06-24/jobs-to-be-done.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 498 KiB

microsite/blog/assets/21-06-24/search-results.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 87 KiB

microsite/core/Footer.js
+1 -1
View File
@@ -33,7 +33,7 @@ class Footer extends React.Component {
<a
href={`/docs/features/software-catalog/software-catalog-overview`}
>
Service Catalog
Software Catalog
</a>
<a href={`/docs/plugins/create-a-plugin`}>Create a Plugin</a>
<a href={`/docs/dls/design`}>Designing for Backstage</a>
microsite/data/plugins/backstage-service-catalog.yaml → microsite/data/plugins/backstage-software-catalog.yaml
+2 -2
View File
@@ -1,10 +1,10 @@
---
title: Backstage Service Catalog
title: Backstage Software Catalog
author: Spotify
authorUrl: https://github.com/spotify
category: Core Feature
description: Manage all your services and software components, all in one place.
documentation: https://backstage.io/docs/features/software-catalog/software-catalog-overview
iconUrl: img/backstage-service-catalog.svg
iconUrl: img/backstage-software-catalog.svg
npmPackageName: '@backstage/plugin-catalog'
order: 1
microsite/package.json
+1 -1
View File
@@ -19,7 +19,7 @@
"@spotify/prettier-config": "^10.0.0",
"docusaurus": "^2.0.0-alpha.70",
"js-yaml": "^4.1.0",
"prettier": "^2.3.1",
"prettier": "^2.3.2",
"yarn-lock-check": "^1.0.5"
},
"prettier": "@spotify/prettier-config"
microsite/pages/en/demos.js
+1 -1
View File
@@ -42,7 +42,7 @@ const Background = props => {
To explore the UI and basic features of Backstage firsthand, go
to: <a href="https://demo.backstage.io">demo.backstage.io</a>.
(Tip: click “All” to view all the example components in the
service catalog.)
software catalog.)
</Block.Paragraph>
</Block.TextBox>
<Block.Graphics>
microsite/pages/en/index.js
+4 -4
View File
@@ -27,7 +27,7 @@ class Index extends React.Component {
An open platform for building developer portals
</Block.Title>
<Block.Paragraph>
Powered by a centralized service catalog, Backstage restores
Powered by a centralized software catalog, Backstage restores
order to your infrastructure and enables your product teams to
ship high-quality code quickly — without compromising autonomy.
</Block.Paragraph>
@@ -102,10 +102,10 @@ class Index extends React.Component {
{' '}
<img
className="Block__GIF"
src={`${baseUrl}animations/backstage-service-catalog-icon-1.gif`}
src={`${baseUrl}animations/backstage-software-catalog-icon-1.gif`}
/>
<Block.Subtitle>
Backstage Service Catalog{' '}
Backstage Software Catalog{' '}
<a
title="Submit feedback for this feature. Click to learn more about this release."
href="https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha"
@@ -192,7 +192,7 @@ class Index extends React.Component {
<ActionBlock className="stripe bg-teal">
<ActionBlock.Title>
Learn more about the service catalog
Learn more about the software catalog
</ActionBlock.Title>
<ActionBlock.Link
href={`https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha`}
microsite/sidebars.json
+2 -1
View File
@@ -157,7 +157,7 @@
"plugins/create-a-plugin",
"plugins/plugin-development",
"plugins/structure-of-a-plugin",
"plugins/integrating-plugin-into-service-catalog",
"plugins/integrating-plugin-into-software-catalog",
"plugins/composability",
{
"type": "subcategory",
@@ -246,6 +246,7 @@
"Tutorials": [
"tutorials/journey",
"tutorials/quickstart-app-plugin",
"tutorials/migrating-away-from-core",
"tutorials/configuring-plugin-databases",
"tutorials/switching-sqlite-postgres"
],
microsite/siteConfig.js
+1 -1
View File
@@ -9,7 +9,7 @@
// site configuration options.
const siteConfig = {
title: 'Backstage Service Catalog and Developer Platform', // Title for your website.
title: 'Backstage Software Catalog and Developer Platform', // Title for your website.
tagline: 'An open platform for building developer portals',
url: 'https://backstage.io', // Your website URL
cname: 'backstage.io',

Some files were not shown because too many files have changed in this diff Show More