diff --git a/.changeset/1724.md b/.changeset/1724.md deleted file mode 100644 index 2ac03f94e9..0000000000 --- a/.changeset/1724.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -'@backstage/cli': minor -'@backstage/plugin-api-docs': minor -'@backstage/plugin-app-backend': minor -'@backstage/plugin-auth-backend': minor -'@backstage/plugin-catalog-graphql': minor -'@backstage/plugin-catalog': minor -'@backstage/plugin-circleci': minor -'@backstage/plugin-explore': minor -'@backstage/plugin-gcp-projects': minor -'@backstage/plugin-github-actions': minor -'@backstage/plugin-gitops-profiles': minor -'@backstage/plugin-graphiql': minor -'@backstage/plugin-jenkins': minor -'@backstage/plugin-kubernetes': minor -'@backstage/plugin-lighthouse': minor -'@backstage/plugin-newrelic': minor -'@backstage/plugin-register-component': minor -'@backstage/plugin-rollbar': minor -'@backstage/plugin-scaffolder': minor -'@backstage/plugin-sentry': minor -'@backstage/plugin-tech-radar': minor -'@backstage/plugin-techdocs': minor -'@backstage/plugin-welcome': minor ---- - -Create backend plugin through CLI diff --git a/.changeset/2284.md b/.changeset/2284.md deleted file mode 100644 index 655cc5a3e8..0000000000 --- a/.changeset/2284.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -'@backstage/core-api': minor -'@backstage/core': minor -'@backstage/plugin-auth-backend': minor ---- - -Add SAML login to backstage - -![](https://user-images.githubusercontent.com/872486/92251660-bb9e3400-eeff-11ea-86fe-1f2a0262cd31.png) - -![](https://user-images.githubusercontent.com/872486/93851658-1a76f200-fce3-11ea-990b-26ca1a327a15.png) diff --git a/.changeset/2515.md b/.changeset/2515.md deleted file mode 100644 index 32f5edd6b7..0000000000 --- a/.changeset/2515.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-cloudbuild': minor ---- - -Releasing Google Cloud Build Plugin diff --git a/.changeset/2532.md b/.changeset/2532.md deleted file mode 100644 index 14307f6c08..0000000000 --- a/.changeset/2532.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/catalog-model': minor ---- - -Add handling and docs for entity references diff --git a/.changeset/2535.md b/.changeset/2535.md deleted file mode 100644 index bd28f3ce03..0000000000 --- a/.changeset/2535.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -'@backstage/core': patch -'@backstage/theme': patch ---- - -Fix banner position and color - -This PR closes: #2245 - -The "fixed" props added to control the position of the banner. When it is set to true the banner will be shown in bottom of that page and the width will be based on the content of the message. - -![](https://user-images.githubusercontent.com/15106494/93765685-999df480-fc15-11ea-8fa5-11cac5836cf1.png) - -![](https://user-images.githubusercontent.com/15106494/93765697-9e62a880-fc15-11ea-92af-b6a7fee4bb21.png) diff --git a/.changeset/2541.md b/.changeset/2541.md deleted file mode 100644 index 1ba29da040..0000000000 --- a/.changeset/2541.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/theme': minor ---- - -Tweak dark mode colors diff --git a/.changeset/2543.md b/.changeset/2543.md deleted file mode 100644 index 00311ade45..0000000000 --- a/.changeset/2543.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -'@backstage/plugin-scaffolder-backend': minor ---- - -Add Azure DevOps support to the scaffolder backend - -This adds support for Azure DevOps to the scaffolder (preparer & publisher). I thought I should get this in there now since #2426 has been merged. I had a previous PR with only the preparer but I closed that in favor of this one. - -I stayed with the 'azure/api' structure but I guess we should try and go the same way as with GitHub here #2501 diff --git a/.changeset/2562.md b/.changeset/2562.md deleted file mode 100644 index 716f370ad9..0000000000 --- a/.changeset/2562.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -'@backstage/create-app': minor -'@backstage/plugin-auth-backend': minor -'@backstage/plugin-techdocs-backend': minor ---- - -Change the default backend plugin mount point to /api diff --git a/.changeset/2563.md b/.changeset/2563.md deleted file mode 100644 index 318d5cf5ef..0000000000 --- a/.changeset/2563.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-github-actions': minor ---- - -Adds a widget to show recent git workflow runs to the github actions plugin. The default setting is the last 5 runs across all branches but both branch and the number of runs are configurable. diff --git a/.changeset/2565.md b/.changeset/2565.md deleted file mode 100644 index 92253101ee..0000000000 --- a/.changeset/2565.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -'@backstage/core-api': patch ---- - -Add initial RouteRefRegistry - -Starting out some work to bring routing back and working as part of the work towards finalizing #1536 - -This is some of the groundwork of an experiment we're working on to enable routing via RouteRefs, while letting the app itself look something like this: - -```jsx -const App = () => ( - - - - {' '} - // catalogRouteRef - - - - - - - // statusRouteRef - - - - - - - - - - // sentryRouteRef - - - - - - - - - - - - - - - -); -``` - -As part of inverting the composition of the app, route refs and routing in general was somewhat broken, intentionally. Right now it's not really possible to easily route to different parts of the app from a plugin, or even different parts of the plugin that are not within the same router. - -The core part of the experiment is to construct a map of ApiRef[] -> path overrides. Each key in the map is the list of route refs to traversed to reach a leaf in the routing tree, and the value is the path override at that point. For example, the above tree would add entries like [techDocsRouteRef] -> '/docs', and [entityRouteRef, apiDocsRouteRef] -> '/api'. By mapping out the entire app in this structure, the idea is that we can navigate to any point in the app using RouteRefs. - -The RouteRefRegistry is an implementation of such a map, and the idea is to add it in master to make it a bit easier to experiment and iterate. This is not an exposed API at this point. - -We've explored a couple of alternatives for how to enable routing, but it's boiled down to either a solution centred around the route map mentioned above, or treating all routes as static and globally unique, with no room for flexibility, customization or conflicts between different plugins. We're starting out pursuing this options 😁. We also expect that a the app-wide routing table will make things like dynamic loading a lot cleaner, as there would be a much more clear handoff between the main chunk and dynamic chunks. diff --git a/.changeset/2575.md b/.changeset/2575.md deleted file mode 100644 index b08f50ed13..0000000000 --- a/.changeset/2575.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/core': minor ---- - -Fix dense in Structured Metadata Table diff --git a/.changeset/2586.md b/.changeset/2586.md deleted file mode 100644 index 568adb8a3e..0000000000 --- a/.changeset/2586.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -'@backstage/catalog-model': minor -'@backstage/plugin-catalog-backend': minor ---- - -Entirely case insensitive read path of entities diff --git a/.changeset/2587.md b/.changeset/2587.md deleted file mode 100644 index 910de1ca04..0000000000 --- a/.changeset/2587.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -'@backstage/catalog-model': minor ---- - -Add the User & Group entities - -A user describes a person, such as an employee, a contractor, or similar. Users belong to Group entities in the catalog. - -A group describes an organizational entity, such as for example a team, a business unit, or a loose collection of people in an interest group. Members of these groups are modeled in the catalog as kind User. diff --git a/.changeset/2597.md b/.changeset/2597.md deleted file mode 100644 index 9db25e8d0e..0000000000 --- a/.changeset/2597.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -'@backstage/catalog-model': minor -'@backstage/plugin-catalog-backend': minor ---- - -Add ApiDefinitionAtLocationProcessor that allows to load a API definition from another location diff --git a/.changeset/2598.md b/.changeset/2598.md deleted file mode 100644 index 03e10e7db8..0000000000 --- a/.changeset/2598.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -'@backstage/plugin-techdocs': minor ---- - -Add a message if techdocs takes long time to load - -Fixes #2416. - -The UI after the change should look like this: - -![techdocs-progress-bar](https://user-images.githubusercontent.com/33940798/94189286-296ac980-fec8-11ea-9051-1b3db938d12f.gif) diff --git a/.changeset/2600.md b/.changeset/2600.md deleted file mode 100644 index 6fc9775fa1..0000000000 --- a/.changeset/2600.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -'@backstage/plugin-techdocs-backend': minor -'@backstage/plugin-proxy-backend': minor -'@backstage/plugin-auth-backend': minor -'@backstage/create-app': minor -'@backstage/backend-common': minor ---- - -Add service discovery interface and implement for single host deployments - -Fixes #1847, #2596 - -Went with an interface similar to the frontend DiscoveryApi, since it's dead simple but still provides a lot of flexibility in the implementation. - -Also ended up with two different methods, one for internal endpoint discovery and one for external. The two use-cases are explained a bit more in the docs, but basically it's service-to-service vs callback URLs. - -This did get me thinking about uniqueness and that we're heading towards a global namespace for backend plugin IDs. That's probably fine, but if we're happy with that we should leverage it a bit more to simplify the backend setup. For example we'd have each plugin provide its own ID and not manually mount on paths in the backend. - -Draft until we're happy with the implementation, then I can add more docs and changelog entry. Also didn't go on a thorough hunt for places where discovery can be used, but I don't think there are many since it's been pretty awkward to do service-to-service communication. diff --git a/.changeset/2603.md b/.changeset/2603.md deleted file mode 100644 index c24d2ea033..0000000000 --- a/.changeset/2603.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -'@backstage/backend-common': minor -'@backstage/create-app': minor ---- - -Make CSP configurable to fix app-backend served app not being able to fetch - -See discussion [here on discord](https://discordapp.com/channels/687207715902193673/687235481154617364/758721460163575850) diff --git a/.changeset/2606.md b/.changeset/2606.md deleted file mode 100644 index f6059e7705..0000000000 --- a/.changeset/2606.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-auth-backend': patch ---- - -Move auth provider router creation to router diff --git a/.changeset/2609.md b/.changeset/2609.md deleted file mode 100644 index 6bb8ab7a40..0000000000 --- a/.changeset/2609.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/create-app': patch ---- - -Sync scaffolded backend with example diff --git a/.changeset/2610.md b/.changeset/2610.md deleted file mode 100644 index 92ec8dcc0c..0000000000 --- a/.changeset/2610.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-circleci': minor ---- - -Refactor to use DiscoveryApi diff --git a/.changeset/2611.md b/.changeset/2611.md deleted file mode 100644 index cbf3129038..0000000000 --- a/.changeset/2611.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/create-app': patch ---- - -Remove discovery api override diff --git a/.changeset/2612.md b/.changeset/2612.md deleted file mode 100644 index bf093d8f77..0000000000 --- a/.changeset/2612.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-jenkins': patch ---- - -Refactor to use DiscoveryApi diff --git a/.changeset/2613.md b/.changeset/2613.md deleted file mode 100644 index cf8c1a155a..0000000000 --- a/.changeset/2613.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -'@backstage/plugin-auth-backend': minor ---- - -Initial implementation of catalog user lookup - -This adds a basic catalog client + method for the Google provider to look up users in the catalog. It expects to find a single user entity in the catalog with a google.com/email annotation that matches the email of the Google profile. - -Right now it falls back to the old behavior of splitting the email, since I don't wanna break the sign-in flow for existing apps, not yet anyway x). - -- Added "@backstage/catalog-model@^0.1.1-alpha.23" as a dependency -- Added "node-fetch@^2.6.1" as a dependency diff --git a/.changeset/2614.md b/.changeset/2614.md deleted file mode 100644 index 7e2660bc80..0000000000 --- a/.changeset/2614.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/create-app': minor ---- - -Default to using internal scope for new plugins diff --git a/.changeset/2615.md b/.changeset/2615.md deleted file mode 100644 index 412b8127c4..0000000000 --- a/.changeset/2615.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/backend-common': minor ---- - -Use localhost to fall back to IPv4 if IPv6 isn't available diff --git a/.changeset/2616.md b/.changeset/2616.md deleted file mode 100644 index 9a70c0e79f..0000000000 --- a/.changeset/2616.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -'@backstage/create-app': minor ---- - -Remove identity-backend - -Not used, and we're heading down the route of identities in the catalog diff --git a/.changeset/2623.md b/.changeset/2623.md deleted file mode 100644 index abd5ce7a4c..0000000000 --- a/.changeset/2623.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -'@backstage/plugin-catalog': minor ---- - -Created EntityNotFound component for catalog which displays the 404 page when entity is not found. - -Fixes #2266 diff --git a/.changeset/2624.md b/.changeset/2624.md deleted file mode 100644 index dcfc800713..0000000000 --- a/.changeset/2624.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -'@backstage/plugin-scaffolder': patch ---- - -Make title meaningful after component creation - -Fixes #2458. - -After the change, the UX should look like this: - -### If the component creation was successful: - -![successfully-created-component](https://user-images.githubusercontent.com/33940798/94339294-8bd1e000-0016-11eb-885b-7936fcc23b63.gif) - -### If the component creation failed: - -![failed-to-create-component](https://user-images.githubusercontent.com/33940798/94339296-90969400-0016-11eb-9a74-ce16b3dd8d88.gif) diff --git a/.changeset/2625-catalog-backend.md b/.changeset/2625-catalog-backend.md deleted file mode 100644 index bcd49dddb2..0000000000 --- a/.changeset/2625-catalog-backend.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -'@backstage/plugin-catalog-backend': patch ---- - -Add codeowners processor - -- Add `codeowners-utils@^1.0.2` as a dependency -- Add `core-js@^3.6.5` as a dependency -- Added new CodeOwnersProcessor diff --git a/.changeset/2625-cli.md b/.changeset/2625-cli.md deleted file mode 100644 index c5a5437b69..0000000000 --- a/.changeset/2625-cli.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -'@backstage/cli': patch ---- - -Add codeowners processor - -- Include ESNext.Promise in TypeScript compilation diff --git a/.changeset/2628.md b/.changeset/2628.md deleted file mode 100644 index 0ac36d456a..0000000000 --- a/.changeset/2628.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -'@backstage/plugin-catalog-backend': minor ---- - -This feature works the same as \$secret does in config - it allows programmatic substitution of values into a document. - -This is particularly useful e.g. for API type entities where you do not want to repeat your entire API spec document inside the catalog-info.yaml file. For those cases, you can instead do something like - -``` -apiVersion: backstage.io/v1alpha1 -kind: API -metadata: - name: my-federated-service -spec: - type: graphql - definition: - $text: ./schema.graphql -``` - -The textual content of that file will be injected as the value of definition, during each refresh loop. Both relative and absolute paths are supported, as well as any HTTP/HTTPS URL pointing to a service that returns the relevant data. - -The initial version supports injection of text file data, and structured data from JSON and YAML files. You can add any handler of your own in addition to these. diff --git a/.changeset/2630.md b/.changeset/2630.md deleted file mode 100644 index 933204e292..0000000000 --- a/.changeset/2630.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -'@backstage/create-app': minor -'@backstage/plugin-catalog-backend': minor ---- - -Allow node v14 and add to master build matrix - -- Upgrade sqlite3@^5.0.0 in @backstage/plugin-catalog-backend -- Add Node 14 to engines in @backstage/create-app diff --git a/.changeset/2637.md b/.changeset/2637.md deleted file mode 100644 index 9d368634b6..0000000000 --- a/.changeset/2637.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -'@backstage/plugin-cost-insights': minor -'@backstage/plugin-explore': minor ---- - -This PR adds Spotify's Cost Insights Tool. Cost Insights explains costs from cloud services in an understandable way, using software terms familiar to your engineers. This tool helps you and your team make trade-offs between cost optimization efforts and your other priorities. - -Cost Insights features: - -Daily cost graph by team or billing account -Cost comparison against configurable business metrics -Insights panels for configurable cloud products your company uses -Cost alerts and recommendations -Selectable time periods for month over month, or quarter over quarter cost comparison -Conversion of cost growth into average engineer cost (configurable) to help optimization trade-off decisions - -![plugin-cost-insights](https://user-images.githubusercontent.com/3030003/94430416-e166d380-0161-11eb-891c-9ce10187683e.gif) - -This PR adds the Cost Insights frontend React plugin with a defined CostInsightsApi. We include an example client with static data in the expected format. This API should talk with a cloud billing backend that aggregates billing data from your cloud provider. - -Fixes #688 💵 diff --git a/.changeset/2639.md b/.changeset/2639.md deleted file mode 100644 index e6a623088e..0000000000 --- a/.changeset/2639.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/cli': minor ---- - -Upgrade dependency `esbuild@0.7.7` diff --git a/.changeset/2641.md b/.changeset/2641.md deleted file mode 100644 index 3b06358e81..0000000000 --- a/.changeset/2641.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-catalog-backend': minor ---- - -Simplify the read function in processors diff --git a/.changeset/2656.md b/.changeset/2656.md deleted file mode 100644 index e253b6b1f6..0000000000 --- a/.changeset/2656.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-auth-backend': minor ---- - -Lookup user in Google Auth Provider diff --git a/.changeset/2657.md b/.changeset/2657.md deleted file mode 100644 index 9aa645d65f..0000000000 --- a/.changeset/2657.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/core': minor ---- - -Added EmptyState component diff --git a/.changeset/2660.md b/.changeset/2660.md deleted file mode 100644 index 758d523f07..0000000000 --- a/.changeset/2660.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-api-docs': patch ---- - -Resolve some dark mode styling issues in asyncAPI specs diff --git a/.changeset/2661.md b/.changeset/2661.md deleted file mode 100644 index e73b0abf26..0000000000 --- a/.changeset/2661.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/core': patch ---- - -Fixed banner component position in DismissableBanner component diff --git a/.changeset/2669-catalog-backend.md b/.changeset/2669-catalog-backend.md deleted file mode 100644 index 32ee5c0f4d..0000000000 --- a/.changeset/2669-catalog-backend.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -'@backstage/plugin-catalog-backend': minor ---- - -Add the ability to import users from GitHub Organization into the catalog. - -The token needs to have the scopes `user:email`, `read:user`, and `read:org`. diff --git a/.changeset/2669-catalog-model.md b/.changeset/2669-catalog-model.md deleted file mode 100644 index b9a2841a1b..0000000000 --- a/.changeset/2669-catalog-model.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/catalog-model': minor ---- - -Add the ability to import users from GitHub Organization into the catalog. diff --git a/.changeset/2669-create-app.md b/.changeset/2669-create-app.md deleted file mode 100644 index e7075ffeb8..0000000000 --- a/.changeset/2669-create-app.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -'@backstage/create-app': minor ---- - -Add the ability to import users from GitHub Organization into the catalog. - -The token needs to have the scopes `user:email`, `read:user`, and `read:org`. diff --git a/.changeset/2674.md b/.changeset/2674.md deleted file mode 100644 index 15a7a0e849..0000000000 --- a/.changeset/2674.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -'@backstage/backend-common': minor -'@backstage/create-app': minor ---- - -Auto-create plugin databases - -Relates to #1598. - -This creates databases for plugins before handing off control to plugins. - -The list of plugins currently need to be hard-coded depending on the installed plugins. A later PR will properly refactor the code to provide a factory pattern where plugins specify what they need, and Knex instances will be provided based on the input. diff --git a/.changeset/2686.md b/.changeset/2686.md deleted file mode 100644 index 8831c1309b..0000000000 --- a/.changeset/2686.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-scaffolder-backend': patch ---- - -Update SSR template to pass CI diff --git a/.changeset/2689.md b/.changeset/2689.md deleted file mode 100644 index be75dd261b..0000000000 --- a/.changeset/2689.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/cli': patch ---- - -Upgrade dependency rollup-plugin-typescript2 to ^0.27.3 diff --git a/.changeset/2722.md b/.changeset/2722.md deleted file mode 100644 index 69642b5797..0000000000 --- a/.changeset/2722.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -'@backstage/plugin-api-docs': minor ---- - -There were some missing features and markdown was not rendered properly, but this is fixed now. - -Details: - -- [`asyncapi/asyncapi-react#149`](https://github.com/asyncapi/asyncapi-react/pull/149) - fix: improve markdown rendering of nested fields -- [`asyncapi/asyncapi-react#150`](https://github.com/asyncapi/asyncapi-react/pull/150) - feat: display the description of channels and operations -- [`asyncapi/asyncapi-react#153`](https://github.com/asyncapi/asyncapi-react/pull/153) - fix: let the list of `enums` break into multiple lines diff --git a/.changeset/2798.md b/.changeset/2798.md deleted file mode 100644 index 2b202142ef..0000000000 --- a/.changeset/2798.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -'@backstage/plugin-catalog-backend': minor ---- - -Use the new `UrlReader` in `PlaceholderProcessor`. -This allows to use the placeholder processor to include API definitions in API entities. -Previously it was only possible to do this if the definition comes from the same location type as the entity itself. diff --git a/.changeset/2800.md b/.changeset/2800.md deleted file mode 100644 index 0e051b0557..0000000000 --- a/.changeset/2800.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -'@backstage/core': minor -'@backstage/core-api': minor ---- - -Updated the `GithubAuth.create` method to configure the default scope of the Github Auth Api. As a result the -default scope is configurable when overwriting the Core Api in the app. - -``` -GithubAuth.create({ - discoveryApi, - oauthRequestApi, - defaultScopes: ['read:user', 'repo'], -}), -``` diff --git a/.changeset/2803.md b/.changeset/2803.md deleted file mode 100644 index 3a4773757f..0000000000 --- a/.changeset/2803.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -'@backstage/plugin-catalog-backend': minor ---- - -Remove the backstage.io/definition-at-location annotation. -The annotation was superseded by the placeholder processor. - -```yaml -apiVersion: backstage.io/v1alpha1 -kind: API -metadata: - name: spotify - description: The Spotify web API - tags: - - spotify - - rest - annotations: - # Don't use this annotation, but the placeholder $text instead (see below). - backstage.io/definition-at-location: 'url:https://raw.githubusercontent.com/APIs-guru/openapi-directory/master/APIs/spotify.com/v1/swagger.yaml' -spec: - type: openapi - lifecycle: production - owner: spotify@example.com - definition: - $text: https://raw.githubusercontent.com/APIs-guru/openapi-directory/master/APIs/spotify.com/v1/swagger.yaml -``` diff --git a/.changeset/2804.md b/.changeset/2804.md deleted file mode 100644 index 5223a24791..0000000000 --- a/.changeset/2804.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -'@backstage/plugin-proxy-backend': minor ---- - -Limit the http headers that are forwarded from the request to a safe set of defaults. -A user can configure additional headers that should be forwarded if the specific applications needs that. - -```yaml -proxy: - '/my-api': - target: 'https://my-api.com/get' - allowedHeaders: - # We need to forward the Authorization header that was provided by the caller - - Authorization -``` diff --git a/.changeset/2874.md b/.changeset/2874.md deleted file mode 100644 index 693962314f..0000000000 --- a/.changeset/2874.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -'@backstage/plugin-catalog-backend': minor ---- - -The way that wiring together a catalog happens, has changed drastically. Now -there is a new class `CatalogBuilder` that does almost all of the heavy lifting -of how to augment/replace pieces of catalog functionality, such as adding -support for custom entities or adding additional processors. - -As the builder was added, a lot of the static methods and builders for default -setups have been removed from classes deep in the hierarchy. Instead, the -builder contains the knowledge of what the defaults are. diff --git a/.changeset/beige-apes-serve.md b/.changeset/beige-apes-serve.md deleted file mode 100644 index 54ee39a85e..0000000000 --- a/.changeset/beige-apes-serve.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'example-app': patch ---- - -Add Pull Request tab to components view. diff --git a/.changeset/cli-parallel-build-options.md b/.changeset/cli-parallel-build-options.md deleted file mode 100644 index 95f9360738..0000000000 --- a/.changeset/cli-parallel-build-options.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -'@backstage/cli': minor ---- - -Adds a new `BACKSTAGE_CLI_BUILD_PARELLEL` environment variable to control -parallelism for some build steps. - -This is useful in CI to help avoid out of memory issues when using `terser`. The -`BACKSTAGE_CLI_BUILD_PARELLEL` environment variable can be set to -`true | false | [integer]` to override the default behaviour. See -[terser-webpack-plugin](https://github.com/webpack-contrib/terser-webpack-plugin#parallel) -for more details. diff --git a/.changeset/codeowner-processor-url-reader.md b/.changeset/codeowner-processor-url-reader.md deleted file mode 100644 index af4eb0997f..0000000000 --- a/.changeset/codeowner-processor-url-reader.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-catalog-backend': minor ---- - -Use the new `UrlReader` in the `CodeOwnersProcessor`. diff --git a/.changeset/cost-insights-strange-rings-smile.md b/.changeset/cost-insights-strange-rings-smile.md new file mode 100644 index 0000000000..c5f4ff9b73 --- /dev/null +++ b/.changeset/cost-insights-strange-rings-smile.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-cost-insights': patch +--- + +remove excessive margin from cost overview banner diff --git a/.changeset/good-islands-cheer.md b/.changeset/cost-insights-ten-carpets-return.md similarity index 53% rename from .changeset/good-islands-cheer.md rename to .changeset/cost-insights-ten-carpets-return.md index 2e7109b312..f378a20eab 100644 --- a/.changeset/good-islands-cheer.md +++ b/.changeset/cost-insights-ten-carpets-return.md @@ -2,4 +2,4 @@ '@backstage/plugin-cost-insights': minor --- -Enable custom alert types in Cost Insights +remove cost insights currency feature flag diff --git a/.changeset/cost-insights-wild-cars-wait.md b/.changeset/cost-insights-wild-cars-wait.md new file mode 100644 index 0000000000..24f84dc56b --- /dev/null +++ b/.changeset/cost-insights-wild-cars-wait.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-cost-insights': patch +--- + +Fix savings/excess display calculation diff --git a/.changeset/create-app-url-reader-update.md b/.changeset/create-app-url-reader-update.md deleted file mode 100644 index eb2e538b77..0000000000 --- a/.changeset/create-app-url-reader-update.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -'example-backend': patch -'@backstage/create-app': patch ---- - -Bump @backstage/catalog-backend and pass the now required UrlReader interface to the plugin diff --git a/.changeset/cyan-plants-dress.md b/.changeset/cyan-plants-dress.md deleted file mode 100644 index 19ebc63e53..0000000000 --- a/.changeset/cyan-plants-dress.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'example-backend': patch ---- - -Pass GitHub token into Scaffolder GitHub Preparer diff --git a/.changeset/flat-bugs-do.md b/.changeset/flat-bugs-do.md deleted file mode 100644 index 672daf657d..0000000000 --- a/.changeset/flat-bugs-do.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -'@backstage/core': patch -'@backstage/plugin-graphiql': patch -'@backstage/plugin-tech-radar': patch -'@backstage/plugin-techdocs': patch ---- - -add test case for Progress component diff --git a/.changeset/fuzzy-falcons-happen.md b/.changeset/fuzzy-falcons-happen.md deleted file mode 100644 index 461ac195d9..0000000000 --- a/.changeset/fuzzy-falcons-happen.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'e2e-test': minor ---- - -Converted into a CLI, use `yarn e2e-test run` to run diff --git a/.changeset/happy-ads-behave.md b/.changeset/happy-ads-behave.md deleted file mode 100644 index f8b889f85c..0000000000 --- a/.changeset/happy-ads-behave.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-scaffolder-backend': patch ---- - -Allow templates to be located on non-default branch diff --git a/.changeset/heavy-berries-hear.md b/.changeset/heavy-berries-hear.md deleted file mode 100644 index 66aa6d93e1..0000000000 --- a/.changeset/heavy-berries-hear.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/core': patch ---- - -Update ItemCard headers to pass color contrast standards. diff --git a/.changeset/hip-experts-dance.md b/.changeset/hip-experts-dance.md new file mode 100644 index 0000000000..f88fe62cd4 --- /dev/null +++ b/.changeset/hip-experts-dance.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +An entity A, that exists in the catalog, can no longer be overwritten by registering a different location that also tries to supply an entity with the same kind+namespace+name. Writes of that new entity will instead be rejected with a log message similar to `Rejecting write of entity Component:default/artist-lookup from file:/Users/freben/dev/github/backstage/packages/catalog-model/examples/components/artist-lookup-component.yaml because entity existed from github:https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml` diff --git a/.changeset/long-ways-count.md b/.changeset/long-ways-count.md deleted file mode 100644 index e04c1225cc..0000000000 --- a/.changeset/long-ways-count.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -'@backstage/plugin-techdocs-backend': minor -'@backstage/create-app': patch ---- - -Updated naming of environment variables. New pattern [NAME]\_TOKEN for Github, Gitlab, Azure & Github enterprise access tokens. - -### Detail: - -- Previously we have to export same token for both, catalog & scaffolder - -```bash -export GITHUB_ACCESS_TOKEN=foo -export GITHUB_PRIVATE_TOKEN=foo -``` - -with latest changes, only single export is sufficient. - -```bash -export GITHUB_TOKEN=foo -export GITLAB_TOKEN=foo -export GHE_TOKEN=foo -export AZURE_TOKEN=foo -``` - -### list: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Old nameNew name
GITHUB_ACCESS_TOKENGITHUB_TOKEN
GITHUB_PRIVATE_TOKENGITHUB_TOKEN
GITLAB_ACCESS_TOKENGITLAB_TOKEN
GITLAB_PRIVATE_TOKENGITLAB_TOKEN
AZURE_PRIVATE_TOKENAZURE_TOKEN
GHE_PRIVATE_TOKENGHE_TOKEN
diff --git a/.changeset/loud-lamps-visit.md b/.changeset/loud-lamps-visit.md deleted file mode 100644 index 9023061643..0000000000 --- a/.changeset/loud-lamps-visit.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/cli': patch ---- - -Including source maps with all packages diff --git a/.changeset/lovely-suits-flash.md b/.changeset/lovely-suits-flash.md deleted file mode 100644 index f093290c85..0000000000 --- a/.changeset/lovely-suits-flash.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/core': patch ---- - -update the test cases of CodeSnippet component diff --git a/.changeset/metal-fishes-learn.md b/.changeset/metal-fishes-learn.md deleted file mode 100644 index d22af83ca0..0000000000 --- a/.changeset/metal-fishes-learn.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/create-app': minor ---- - -The default mount point for backend plugins have been changed to /api. These changes are done in the backend package itself, so it is recommended that you sync up existing backend packages with this new pattern. diff --git a/.changeset/new-url-reader.md b/.changeset/new-url-reader.md deleted file mode 100644 index 94758c5bc1..0000000000 --- a/.changeset/new-url-reader.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -'@backstage/backend-common': patch ---- - -Added new UrlReader interface for reading opaque data from URLs with different providers. - -This new URL reading system is intended as a replacement for the various integrations towards -external systems in the catalog, scaffolder, and techdocs. It is configured via a new top-level -config section called 'integrations'. - -Along with the UrlReader interface is a new UrlReaders class, which exposes static factory -methods for instantiating readers that can read from many different integrations simultaneously. diff --git a/.changeset/ninety-gifts-guess.md b/.changeset/ninety-gifts-guess.md new file mode 100644 index 0000000000..bdd20322ec --- /dev/null +++ b/.changeset/ninety-gifts-guess.md @@ -0,0 +1,6 @@ +--- +'@backstage/backend-common': patch +'@backstage/integration': patch +--- + +Added the integration package diff --git a/.changeset/ninety-pens-poke.md b/.changeset/ninety-pens-poke.md deleted file mode 100644 index 94bcb06749..0000000000 --- a/.changeset/ninety-pens-poke.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/create-app': patch ---- - -Fix for configured templates using 'url' locations even though it's not supported yet diff --git a/.changeset/odd-camels-begin.md b/.changeset/odd-camels-begin.md new file mode 100644 index 0000000000..d28d729609 --- /dev/null +++ b/.changeset/odd-camels-begin.md @@ -0,0 +1,5 @@ +--- +'@backstage/backend-common': minor +--- + +Refactored UrlReader.readTree to be required and accept (url, options) diff --git a/.changeset/old-eagles-admire.md b/.changeset/old-eagles-admire.md deleted file mode 100644 index 0729b6439d..0000000000 --- a/.changeset/old-eagles-admire.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -'@backstage/backend-common': minor -'@backstage/cli': minor ---- - -Use APP_ENV before NODE_ENV for determining what config to load diff --git a/.changeset/old-falcons-jump.md b/.changeset/old-falcons-jump.md deleted file mode 100644 index 107d75ff88..0000000000 --- a/.changeset/old-falcons-jump.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -'@backstage/plugin-newrelic': minor ---- - -The New Relic plugin now uses the Backstage proxy to communicate with New Relic's API. - -Please update your `app-config.yaml` as follows: - -```yaml -# Old Config -newrelic: - api: - baseUrl: 'https://api.newrelic.com/v2' - key: NEW_RELIC_REST_API_KEY -``` - -```yaml -# New Config -proxy: - '/newrelic/apm/api': - target: https://api.newrelic.com/v2 - headers: - X-Api-Key: - $env: NEW_RELIC_REST_API_KEY -``` diff --git a/.changeset/olive-bikes-jog.md b/.changeset/olive-bikes-jog.md deleted file mode 100644 index fdbf1e0d9f..0000000000 --- a/.changeset/olive-bikes-jog.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/core': patch ---- - -add test cases for Status components diff --git a/.changeset/pretty-cups-joke.md b/.changeset/pretty-cups-joke.md deleted file mode 100644 index 49a1db2a75..0000000000 --- a/.changeset/pretty-cups-joke.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-scaffolder-backend': patch ---- - -Add authentication token to Scaffolder GitHub Preparer diff --git a/.changeset/proud-eagles-grow.md b/.changeset/proud-eagles-grow.md deleted file mode 100644 index ef83a4ad26..0000000000 --- a/.changeset/proud-eagles-grow.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/cli': patch ---- - -Fixed duplicate help output, and print help on invalid command diff --git a/.changeset/raghu-is-great.md b/.changeset/raghu-is-great.md deleted file mode 100644 index 805e49f3e8..0000000000 --- a/.changeset/raghu-is-great.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -'@backstage/plugin-catalog-backend': minor ---- - -Renamed the `LocationProcessor` class to `CatalogProcessor`. - -Likewise, renamed `LocationProcessorResult`, `LocationProcessorLocationResult`, -`LocationProcessorDataResult`, `LocationProcessorEntityResult`, -`LocationProcessorErrorResult`, and `LocationProcessorEmit` to their `Catalog*` -counterparts. diff --git a/.changeset/red-games-float.md b/.changeset/red-games-float.md deleted file mode 100644 index 6eabba26a4..0000000000 --- a/.changeset/red-games-float.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -'@backstage/plugin-cost-insights': minor ---- - -- getProjectDailyCost and getGroupDailyCost no longer accept a metric as a parameter -- getDailyMetricData added to API for fetching daily metric data for given interval -- dailyCost removed as configurable metric -- default field added to metric configuration for displaying comparison metric data in top panel -- Metric.kind can no longer be null -- MetricData type added diff --git a/.changeset/remove-location-processor-read.md b/.changeset/remove-location-processor-read.md deleted file mode 100644 index 78aea6d820..0000000000 --- a/.changeset/remove-location-processor-read.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -'@backstage/plugin-catalog-backend': minor ---- - -Remove the `read` argument of `LocationProcessor.processEntity`. -Instead, pass the `UrlReader` into the constructor of your `LocationProcessor`. diff --git a/.changeset/selfish-bats-perform.md b/.changeset/selfish-bats-perform.md deleted file mode 100644 index e4d05c088c..0000000000 --- a/.changeset/selfish-bats-perform.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -'@backstage/plugin-scaffolder': patch -'@backstage/plugin-scaffolder-backend': patch ---- - -The new `scaffolder.github.baseUrl` config property allows to specify a custom base url for GitHub enterprise instances diff --git a/.changeset/short-secrets.md b/.changeset/short-secrets.md deleted file mode 100644 index 72cb059979..0000000000 --- a/.changeset/short-secrets.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/config-loader': minor ---- - -Added support for new shorthand when defining secrets, where `$env: ENV` can be used instead of `$secret: { env: ENV }` etc. diff --git a/.changeset/slow-experts-peel.md b/.changeset/slow-experts-peel.md deleted file mode 100644 index ed9c7af21e..0000000000 --- a/.changeset/slow-experts-peel.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-tech-radar': patch ---- - -fix the horizontal scrolling issue in the RadarPage component diff --git a/.changeset/spotty-apples-visit.md b/.changeset/spotty-apples-visit.md deleted file mode 100644 index ba481fa052..0000000000 --- a/.changeset/spotty-apples-visit.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-auth-backend': patch ---- - -Better presentation of authentication errors diff --git a/.changeset/swift-peas-argue.md b/.changeset/swift-peas-argue.md deleted file mode 100644 index d78d844d45..0000000000 --- a/.changeset/swift-peas-argue.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/core': patch ---- - -give aria-label attribute to Status Ok, Warning and Error diff --git a/.changeset/url-reader-processor.md b/.changeset/url-reader-processor.md deleted file mode 100644 index 40fef3c106..0000000000 --- a/.changeset/url-reader-processor.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@backstage/plugin-catalog-backend': minor ---- - -The catalog backend UrlReaderProcessor now uses a UrlReader from @backstage/backend-common, which must now be supplied to the constructor. diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 3df1031034..d818c0d6b5 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -4,13 +4,10 @@ # The last matching pattern takes precedence. # https://help.github.com/articles/about-codeowners/ -* @spotify/backstage-core -/docs/features/techdocs @spotify/techdocs-core -/plugins/cost-insights @spotify/silver-lining +* @backstage/maintainers +/docs/features/techdocs @backstage/techdocs-core +/plugins/cost-insights @backstage/silver-lining /plugins/cloudbuild @trivago/ebarrios -/plugins/techdocs @spotify/techdocs-core -/plugins/techdocs-backend @spotify/techdocs-core -/packages/techdocs-cli @spotify/techdocs-core -/packages/techdocs-container @spotify/techdocs-core -/.github/workflows/techdocs.yml @spotify/techdocs-core -/.github/workflows/techdocs-pypi.yml @spotify/techdocs-core +/plugins/techdocs @backstage/techdocs-core +/plugins/techdocs-backend @backstage/techdocs-core +/.changeset/cost-insights-* @backstage/silver-lining diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index de7ce773bb..d68af23491 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -7,7 +7,7 @@ -- [ ] A changeset describing the change and affected packages. ([more info](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md#creating-changesets)) +- [ ] A changeset describing the change and affected packages. ([more info](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md#creating-changesets)) - [ ] Added or updated documentation - [ ] Tests for new functionality and regression tests for bug fixes - [ ] Screenshots attached (for UI changes) diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt index 0cbd0ffa05..3c5fa34adc 100644 --- a/.github/styles/vocab.txt +++ b/.github/styles/vocab.txt @@ -62,6 +62,7 @@ Firekube Fredrik github Github +gitlab Gitlab graphql graphviz @@ -91,6 +92,7 @@ learnings lerna Lerna magiclink +Maintainership mailto Malus md @@ -189,6 +191,7 @@ toc tolerations Tolerations toolsets +tooltip touchpoints ui upvote diff --git a/.github/workflows/changeset.yml b/.github/workflows/changeset.yml index ac7872ea93..a557b4921b 100644 --- a/.github/workflows/changeset.yml +++ b/.github/workflows/changeset.yml @@ -15,5 +15,8 @@ jobs: run: yarn --frozen-lockfile - name: Create Release Pull Request uses: changesets/action@master + with: + # Calls out to `changeset version`, but also runs prettier + version: yarn release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d00f304b58..75c6a13cd2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -67,7 +67,7 @@ jobs: continue-on-error: true - name: verify doc links - run: node docs/verify-links.js + run: node scripts/verify-links.js - name: prettier run: yarn prettier:check diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 335bd80109..3f59b815b3 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -6,6 +6,8 @@ on: jobs: build: + if: github.repository == 'backstage/backstage' # prevent running on forks + runs-on: ubuntu-latest strategy: diff --git a/.github/workflows/techdocs-project-board.yml b/.github/workflows/techdocs-project-board.yml index b389cf6bf5..a8d476f713 100644 --- a/.github/workflows/techdocs-project-board.yml +++ b/.github/workflows/techdocs-project-board.yml @@ -1,6 +1,7 @@ name: Automatically add new TechDocs Issues and PRs to the GitHub project board -# Development of TechDocs in Backstage is managed by this Kanban board - https://github.com/spotify/backstage/projects/5 -# New issues with TechDocs in their title or docs-like-code label will be added to the board. +# Development of TechDocs in Backstage is managed by this Kanban board - https://github.com/orgs/backstage/projects/1 +# New issues and PRs with TechDocs in their title or docs-like-code label will be added to the board. +# Caveat: New PRs created from forks will not be added since GitHub actions don't share credentials with forks. on: issues: @@ -9,7 +10,7 @@ on: types: [opened, reopened, labeled, edited] env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + MY_GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }} jobs: assign_issue_or_pr_to_project: @@ -23,7 +24,7 @@ jobs: contains(github.event.issue.title, 'techdocs') || contains(github.event.issue.title, 'Techdocs') with: - project: 'https://github.com/spotify/backstage/projects/5' + project: 'https://github.com/orgs/backstage/projects/1' column_name: 'Incoming' - name: Assign new issue to Incoming based on its label. @@ -31,7 +32,7 @@ jobs: if: | contains(github.event.issue.labels.*.name, 'docs-like-code') with: - project: 'https://github.com/spotify/backstage/projects/5' + project: 'https://github.com/orgs/backstage/projects/1' column_name: 'Incoming' - name: Assign new PR to Incoming based on its title. @@ -41,7 +42,7 @@ jobs: contains(github.event.pull_request.title, 'techdocs') || contains(github.event.pull_request.title, 'Techdocs') with: - project: 'https://github.com/spotify/backstage/projects/5' + project: 'https://github.com/orgs/backstage/projects/1' column_name: 'Incoming' - name: Assign new PR to Incoming based on its label. @@ -49,5 +50,5 @@ jobs: if: | contains(github.event.pull_request.labels.*.name, 'docs-like-code') with: - project: 'https://github.com/spotify/backstage/projects/5' + project: 'https://github.com/orgs/backstage/projects/1' column_name: 'Incoming' diff --git a/.github/workflows/techdocs-pypi.yml b/.github/workflows/techdocs-pypi.yml deleted file mode 100644 index 7680cb98b0..0000000000 --- a/.github/workflows/techdocs-pypi.yml +++ /dev/null @@ -1,37 +0,0 @@ -name: Master Build TechDocs PyPI Publish - -on: - push: - branches: [master] - paths: - - '.github/workflows/techdocs-pypi.yml' - - 'packages/techdocs-container/**' - -jobs: - build: - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: [ubuntu-latest] - python-version: [3.7] - - steps: - # Publish techdocs-core to PyPI - - uses: actions/checkout@v2 - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@master - with: - python-version: 3.7 - - name: Build Python distribution - working-directory: ./packages/techdocs-container/techdocs-core - run: | - pip install wheel - rm -rf dist - python setup.py bdist_wheel sdist --formats gztar - - name: Publish a Python distribution to PyPI - uses: pypa/gh-action-pypi-publish@master - with: - user: __token__ - password: ${{ secrets.PYPI_API_KEY }} - packages_dir: ./packages/techdocs-container/techdocs-core/dist diff --git a/.github/workflows/techdocs.yml b/.github/workflows/techdocs.yml deleted file mode 100644 index 95b68c9376..0000000000 --- a/.github/workflows/techdocs.yml +++ /dev/null @@ -1,44 +0,0 @@ -name: TechDocs - -on: - pull_request: - paths: - - '.github/workflows/techdocs.yml' - - 'packages/techdocs-container/**' - - 'packages/techdocs-cli/**' - - 'plugins/techdocs/**' - - 'plugins/techdocs-backend/**' - -jobs: - build: - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: [ubuntu-latest] - python-version: [3.7] - - env: - TECHDOCS_CORE_PATH: ./packages/techdocs-container/techdocs-core - - name: Python ${{ matrix.node-version }} on ${{ matrix.os }} - steps: - - uses: actions/checkout@v2 - - # Build Docker Image - - name: Build Docker image - uses: docker/build-push-action@v1.1.0 - with: - path: packages/techdocs-container - push: false - - # Lint Python code for techdocs-core package - - name: Prepare Python environment - run: | - python3 -m pip install --index-url https://pypi.org/simple/ setuptools - python3 -m pip install --upgrade pip - python3 -m pip install --index-url https://pypi.org/simple/ -r $TECHDOCS_CORE_PATH/requirements.txt - - - name: Lint techdocs-core package - run: | - python3 -m black --check $TECHDOCS_CORE_PATH/src diff --git a/.gitignore b/.gitignore index e7d294d55a..5c27601791 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,11 @@ -.idea/ +# macOS .DS_Store + +# IntelliJ +.idea/ +*.iml + +# Visual Studio Code .vscode/ .vsls.json diff --git a/.yarnrc b/.yarnrc index f465c5c5e6..6b56b971d7 100644 --- a/.yarnrc +++ b/.yarnrc @@ -3,6 +3,7 @@ registry "https://registry.npmjs.org/" +disable-self-update-check true lastUpdateCheck 1580389148099 yarn-path ".yarn/releases/yarn-1.22.1.js" network-timeout 600000 diff --git a/CHANGELOG.md b/CHANGELOG.md index 0bcce2966f..1ac33ca7f8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,30 +2,42 @@ This is a best-effort changelog where we manually collect breaking changes. It is not an exhaustive list of all changes or even features added. -If you encounter issues while upgrading to a newer version, don't hesitate to reach out on [Discord](https://discord.gg/EBHEGzX) or [open an issue](https://github.com/spotify/backstage/issues/new/choose)! +If you encounter issues while upgrading to a newer version, don't hesitate to reach out on [Discord](https://discord.gg/EBHEGzX) or [open an issue](https://github.com/backstage/backstage/issues/new/choose)! ## Next Release > Collect changes for the next release below +## v0.1.1-alpha.26 + +### @backstage/cli + +- Configuration files are no longer selected through `APP_ENV` or `NODE_ENV`. The default configuration files are `app-config.yaml` and, fix it exists, `app-config.local.yaml` in the repo root. To load a different set of files, use `--config ` arguments. + +### @backstage/backend-common + +- Configuration files are no longer selected through `APP_ENV` or `NODE_ENV`. The default configuration files are `app-config.yaml` and, fix it exists, `app-config.local.yaml` in the repo root. To load a different set of files, use `--config ` arguments. + +## v0.1.1-alpha.25 + ### @backstage/cli - The recommended way to set the configuration environment is now to use `APP_ENV` instead of `NODE_ENV`. ### Backend (example-backend, or backends created with @backstage/create-app) -- A plugin database manager has been created, and plugins can now accept that interface as an argument during initialisation. Notably, the `auth` plugin has a [`createRouter` signature change](./plugins/auth-backend/src/service/router.ts). See [packages/backend/src/index.ts](./packages/backend/src/index.ts) on how to set it up. [#2697](https://github.com/spotify/backstage/pull/2697) +- A plugin database manager has been created, and plugins can now accept that interface as an argument during initialisation. Notably, the `auth` plugin has a [`createRouter` signature change](./plugins/auth-backend/src/service/router.ts). See [packages/backend/src/index.ts](./packages/backend/src/index.ts) on how to set it up. [#2697](https://github.com/backstage/backstage/pull/2697) ## v0.1.1-alpha.24 ### Backend (example-backend, or backends created with @backstage/create-app) -- The default mount point for backend plugins have been changed to `/api`. These changes are done in the backend package itself, so it is recommended that you sync up existing backend packages with this new pattern. [#2562](https://github.com/spotify/backstage/pull/2562) -- A service discovery mechanism for backend plugins has been added, and is now a requirement for several backend plugins. See [packages/backend/src/index.ts](./packages/backend/src/index.ts) for how to set it up using `SingleHostDiscovery` from `@backstage/backend-common`. Note that the default base path for plugins is set to `/api` to that change, but it can be set to use the old behavior via the `basePath` option. [#2600](https://github.com/spotify/backstage/pull/2600) +- The default mount point for backend plugins have been changed to `/api`. These changes are done in the backend package itself, so it is recommended that you sync up existing backend packages with this new pattern. [#2562](https://github.com/backstage/backstage/pull/2562) +- A service discovery mechanism for backend plugins has been added, and is now a requirement for several backend plugins. See [packages/backend/src/index.ts](./packages/backend/src/index.ts) for how to set it up using `SingleHostDiscovery` from `@backstage/backend-common`. Note that the default base path for plugins is set to `/api` to that change, but it can be set to use the old behavior via the `basePath` option. [#2600](https://github.com/backstage/backstage/pull/2600) ### @backstage/auth-backend -- The default mount path of backend plugins was changed to `/api/:pluginId`, and as part of that it was needed to enable configuration of the base path of the auth backend, so that it can construct redirect URLs correctly. Note that you will also need to reconfigure any allowed redirect URLs to include `/api` if you switch to the new recommended pattern. [#2562](https://github.com/spotify/backstage/pull/2562) +- The default mount path of backend plugins was changed to `/api/:pluginId`, and as part of that it was needed to enable configuration of the base path of the auth backend, so that it can construct redirect URLs correctly. Note that you will also need to reconfigure any allowed redirect URLs to include `/api` if you switch to the new recommended pattern. [#2562](https://github.com/backstage/backstage/pull/2562) - The auth backend now requires an implementation of `PluginEndpointDiscovery` from `@backstage/backend-common` to be passed in as `discovery`. See the changes to `@backstage/backend`. ### @backstage/proxy-backend @@ -38,28 +50,28 @@ If you encounter issues while upgrading to a newer version, don't hesitate to re ### @backstage/plugin-identity-backend -- This plugin was removed, remove it from your backend if it's there. [#2616](https://github.com/spotify/backstage/pull/2616) +- This plugin was removed, remove it from your backend if it's there. [#2616](https://github.com/backstage/backstage/pull/2616) ## v0.1.1-alpha.23 ### @backstage/core -- Renamed `SessionStateApi` to `SessionApi` and `logout` to `signOut`. Custom implementations of the `SingInPage` app-component will need to rename their `logout` function. The different auth provider items for the `UserSettingsMenu` have been consolidated into a single `ProviderSettingsItem`, meaning you need to replace existing usages of `OAuthProviderSettings` and `OIDCProviderSettings`. [#2555](https://github.com/spotify/backstage/pull/2555). +- Renamed `SessionStateApi` to `SessionApi` and `logout` to `signOut`. Custom implementations of the `SingInPage` app-component will need to rename their `logout` function. The different auth provider items for the `UserSettingsMenu` have been consolidated into a single `ProviderSettingsItem`, meaning you need to replace existing usages of `OAuthProviderSettings` and `OIDCProviderSettings`. [#2555](https://github.com/backstage/backstage/pull/2555). ## v0.1.1-alpha.22 ### @backstage/core -- Introduced initial version of an inverted app/plugin relationship, where plugins export components for apps to use, instead registering themselves directly into the app. This enables more fine-grained control of plugin features, and also composition of plugins such as catalog pages with additional cards and tabs. This breaks the use of `RouteRef`s, and there will be more changes related to this in the future, but this change lays the initial foundation. See `packages/app` and followup PRs for how to update plugins for this change. [#2076](https://github.com/spotify/backstage/pull/2076) -- Switch to an automatic dependency injection mechanism for all Utility APIs, allowing plugins to ship default implementations of their APIs. See [https://backstage.io/docs/api/utility-apis](https://backstage.io/docs/api/utility-apis). [#2285](https://github.com/spotify/backstage/pull/2285) +- Introduced initial version of an inverted app/plugin relationship, where plugins export components for apps to use, instead registering themselves directly into the app. This enables more fine-grained control of plugin features, and also composition of plugins such as catalog pages with additional cards and tabs. This breaks the use of `RouteRef`s, and there will be more changes related to this in the future, but this change lays the initial foundation. See `packages/app` and followup PRs for how to update plugins for this change. [#2076](https://github.com/backstage/backstage/pull/2076) +- Switch to an automatic dependency injection mechanism for all Utility APIs, allowing plugins to ship default implementations of their APIs. See [https://backstage.io/docs/api/utility-apis](https://backstage.io/docs/api/utility-apis). [#2285](https://github.com/backstage/backstage/pull/2285) ### @backstage/cli -- Change `backstage-cli backend:build-image` to forward all args to `docker image build`, instead of just tag. Also add `--build` flag for building all dependent packages before packaging the workspace for the docker build. [#2299](https://github.com/spotify/backstage/pull/2299) +- Change `backstage-cli backend:build-image` to forward all args to `docker image build`, instead of just tag. Also add `--build` flag for building all dependent packages before packaging the workspace for the docker build. [#2299](https://github.com/backstage/backstage/pull/2299) ### @backstage/create-app -- Change root `tsc` output dir to `dist-types`, in order to allow for standalone plugin repos. [#2278](https://github.com/spotify/backstage/pull/2278) +- Change root `tsc` output dir to `dist-types`, in order to allow for standalone plugin repos. [#2278](https://github.com/backstage/backstage/pull/2278) ### @backstage/catalog-backend @@ -67,7 +79,7 @@ If you encounter issues while upgrading to a newer version, don't hesitate to re ## v0.1.1-alpha.21 -- Added many more frontend plugins to the template along with the sidebar. [#1942](https://github.com/spotify/backstage/pull/1942), [#2084](https://github.com/spotify/backstage/pull/2084) +- Added many more frontend plugins to the template along with the sidebar. [#1942](https://github.com/backstage/backstage/pull/1942), [#2084](https://github.com/backstage/backstage/pull/2084) ### @backstage/core @@ -78,14 +90,14 @@ If you encounter issues while upgrading to a newer version, don't hesitate to re ### @backstage/cli -- Set `NODE_ENV` to `test` when running test. [#2214](https://github.com/spotify/backstage/pull/2214) +- Set `NODE_ENV` to `test` when running test. [#2214](https://github.com/backstage/backstage/pull/2214) -- Fix for backend plugins names requiring to be prefixed with `@backstage` to build. [#2224](https://github.com/spotify/backstage/pull/2224) +- Fix for backend plugins names requiring to be prefixed with `@backstage` to build. [#2224](https://github.com/backstage/backstage/pull/2224) ### @backstage/backend-common - The backend plugin - [service builder](https://github.com/spotify/backstage/blob/master/packages/backend-common/src/service/lib/ServiceBuilderImpl.ts) + [service builder](https://github.com/backstage/backstage/blob/master/packages/backend-common/src/service/lib/ServiceBuilderImpl.ts) no longer adds `express.json()` automatically to all routes. While convenient in a lot of cases, it also led to problems where for example the proxy middleware could hang because the body had already been altered and could not @@ -95,61 +107,61 @@ If you encounter issues while upgrading to a newer version, don't hesitate to re ### @backstage/catalog-backend -- Add rules configuration for catalog location and entity kinds. The default rules should cover most use-cases, but you may need to allow specific entity kinds when using things like Template or Group entities. [#2118](https://github.com/spotify/backstage/pull/2118) +- Add rules configuration for catalog location and entity kinds. The default rules should cover most use-cases, but you may need to allow specific entity kinds when using things like Template or Group entities. [#2118](https://github.com/backstage/backstage/pull/2118) ## v0.1.1-alpha.20 ### @backstage/cli -- Use config files according to `NODE_ENV` when serving and building frontend packages. [#2077](https://github.com/spotify/backstage/pull/2077) +- Use config files according to `NODE_ENV` when serving and building frontend packages. [#2077](https://github.com/backstage/backstage/pull/2077) -- Pin `rollup-plugin-dts` to avoid a later broken version. [#2097](https://github.com/spotify/backstage/pull/2097) +- Pin `rollup-plugin-dts` to avoid a later broken version. [#2097](https://github.com/backstage/backstage/pull/2097) ## v0.1.1-alpha.19 ### @backstage/backend-common -- Allow listen host and port to be configured separately, in order to support PORT environment variables. [#1950](https://github.com/spotify/backstage/pull/1950) +- Allow listen host and port to be configured separately, in order to support PORT environment variables. [#1950](https://github.com/backstage/backstage/pull/1950) ### @backstage/core -- Added new `DiscoveryApi` for discovering backend endpoint in the frontend, and use in most plugins. See [packages/app/src/apis.ts](https://github.com/spotify/backstage/blob/master/packages/app/src/apis.ts) for how to register in your app. [#2074](https://github.com/spotify/backstage/pull/2074) +- Added new `DiscoveryApi` for discovering backend endpoint in the frontend, and use in most plugins. See [packages/app/src/apis.ts](https://github.com/backstage/backstage/blob/master/packages/app/src/apis.ts) for how to register in your app. [#2074](https://github.com/backstage/backstage/pull/2074) ### @backstage/create-app -- Added catalog and scaffolder frontend plugins to the template along with the sidebar. [#1942](https://github.com/spotify/backstage/pull/1942), [#2084](https://github.com/spotify/backstage/pull/2084) -- Many plugins have been added to the catalog and will for now be required to be added to separate apps as well. This will be solved as [#1536](https://github.com/spotify/backstage/issues/1536) gets sorted out, but for now you may need to install some plugins just to get pages to work. +- Added catalog and scaffolder frontend plugins to the template along with the sidebar. [#1942](https://github.com/backstage/backstage/pull/1942), [#2084](https://github.com/backstage/backstage/pull/2084) +- Many plugins have been added to the catalog and will for now be required to be added to separate apps as well. This will be solved as [#1536](https://github.com/backstage/backstage/issues/1536) gets sorted out, but for now you may need to install some plugins just to get pages to work. ### @backstage/catalog-backend -- Added the possibility to add static locations via `app-config.yaml`. This changed the signature of `new LocationReaders(logger)` inside `packages/backend/src/plugins/catalog.ts` to `new LocationReaders({config, logger})`. [#1890](https://github.com/spotify/backstage/pull/1890) +- Added the possibility to add static locations via `app-config.yaml`. This changed the signature of `new LocationReaders(logger)` inside `packages/backend/src/plugins/catalog.ts` to `new LocationReaders({config, logger})`. [#1890](https://github.com/backstage/backstage/pull/1890) ### @backstage/theme -- Changed the type signature of the palette, removing `sidebar: string` and adding `navigation: { background: string; indicator: string}`. [#1880](https://github.com/spotify/backstage/pull/1880) +- Changed the type signature of the palette, removing `sidebar: string` and adding `navigation: { background: string; indicator: string}`. [#1880](https://github.com/backstage/backstage/pull/1880) ## v0.1.1-alpha.18 ### @backstage/catalog-backend -- Fixed an issue with duplicated location logs. Applying the database migrations from this fix will clear the existing migration logs. [#1836](https://github.com/spotify/backstage/pull/1836) +- Fixed an issue with duplicated location logs. Applying the database migrations from this fix will clear the existing migration logs. [#1836](https://github.com/backstage/backstage/pull/1836) ### @backstage/auth-backend This version fixes a breakage in CSP policies set by the auth backend. If you're facing trouble with auth in alpha.17, upgrade to alpha.18. -- OAuth redirect URLs no longer receive the `env` parameter, as it is now passed through state instead. This will likely require a reconfiguration of the OAuth app, where a redirect URL like `http://localhost:7000/auth/google/handler/frame?env=development` should now be configured as `http://localhost:7000/auth/google/handler/frame`. [#1812](https://github.com/spotify/backstage/pull/1812) +- OAuth redirect URLs no longer receive the `env` parameter, as it is now passed through state instead. This will likely require a reconfiguration of the OAuth app, where a redirect URL like `http://localhost:7000/auth/google/handler/frame?env=development` should now be configured as `http://localhost:7000/auth/google/handler/frame`. [#1812](https://github.com/backstage/backstage/pull/1812) ### @backstage/core -- `SignInPage` props have been changed to receive a list of provider objects instead of simple string identifiers for all but the `'guest'` and `'custom'` providers. This opens up for configuration of custom providers, but may break existing configurations. See [packages/app/src/App.tsx](https://github.com/spotify/backstage/blob/032ba401af36a760efdac41668d7000ccf09bc57/packages/app/src/App.tsx#L36) and [packages/app/src/identityProviders.ts](https://github.com/spotify/backstage/blob/032ba401af36a760efdac41668d7000ccf09bc57/packages/app/src/identityProviders.ts#L24) for how to bring back the existing providers. [#1816](https://github.com/spotify/backstage/pull/1816) +- `SignInPage` props have been changed to receive a list of provider objects instead of simple string identifiers for all but the `'guest'` and `'custom'` providers. This opens up for configuration of custom providers, but may break existing configurations. See [packages/app/src/App.tsx](https://github.com/backstage/backstage/blob/032ba401af36a760efdac41668d7000ccf09bc57/packages/app/src/App.tsx#L36) and [packages/app/src/identityProviders.ts](https://github.com/backstage/backstage/blob/032ba401af36a760efdac41668d7000ccf09bc57/packages/app/src/identityProviders.ts#L24) for how to bring back the existing providers. [#1816](https://github.com/backstage/backstage/pull/1816) ## v0.1.1-alpha.17 ### @backstage/techdocs-backend -- The techdocs backend now requires more configuration to be supplied when creating the router. See [packages/backend/src/plugins/techdocs.ts](https://github.com/spotify/backstage/blob/0201fd9b4a52429519dd59e9184106ba69456deb/packages/backend/src/plugins/techdocs.ts#L42) for an example. [#1736](https://github.com/spotify/backstage/pull/1736) +- The techdocs backend now requires more configuration to be supplied when creating the router. See [packages/backend/src/plugins/techdocs.ts](https://github.com/backstage/backstage/blob/0201fd9b4a52429519dd59e9184106ba69456deb/packages/backend/src/plugins/techdocs.ts#L42) for an example. [#1736](https://github.com/backstage/backstage/pull/1736) ### @backstage/cli -- The `create-app` command was moved out from the CLI to a standalone package. It's now invoked with `npx @backstage/create-app` instead. [#1745](https://github.com/spotify/backstage/pull/1745) +- The `create-app` command was moved out from the CLI to a standalone package. It's now invoked with `npx @backstage/create-app` instead. [#1745](https://github.com/backstage/backstage/pull/1745) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7edbc6d17b..b7157d9f05 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,11 +12,11 @@ Backstage is released under the Apache2.0 License, and original creations contri ## Report bugs -No one likes bugs. Report bugs as an issue [here](https://github.com/spotify/backstage/issues/new?template=bug_template.md). +No one likes bugs. Report bugs as an issue [here](https://github.com/backstage/backstage/issues/new?template=bug_template.md). ## Fix bugs or build new features -Look through the GitHub issues for [bugs](https://github.com/spotify/backstage/labels/bugs), [good first issues](https://github.com/spotify/backstage/labels/good%20first%20issue) or [help wanted](https://github.com/spotify/backstage/labels/help%20wanted). +Look through the GitHub issues for [bugs](https://github.com/backstage/backstage/labels/bugs), [good first issues](https://github.com/backstage/backstage/labels/good%20first%20issue) or [help wanted](https://github.com/backstage/backstage/labels/help%20wanted). ## Build a plugin @@ -24,17 +24,17 @@ The value of Backstage grows with every new plugin that gets added. Wouldn't it A great reference example of a plugin can be found on [our blog](https://backstage.io/blog/2020/04/06/lighthouse-plugin) (thanks [@fastfrwrd](https://github.com/fastfrwrd)!) -What kind of plugins should/could be created? Some inspiration from the 120+ plugins that we have developed inside Spotify can be found [here](https://backstage.io/demos), but we will keep a running list of suggestions labeled with [[plugin]](https://github.com/spotify/backstage/labels/plugin). +What kind of plugins should/could be created? Some inspiration from the 120+ plugins that we have developed inside Spotify can be found [here](https://backstage.io/demos), but we will keep a running list of suggestions labeled with [[plugin]](https://github.com/backstage/backstage/labels/plugin). ## Suggesting a plugin -If you start developing a plugin that you aim to release as open source, we suggest that you create a [new Issue](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). This helps the community know what plugins are in development. +If you start developing a plugin that you aim to release as open source, we suggest that you create a [new Issue](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). 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. ## Adding Non-code Contributions -Since there is such a large landscape of possible development, build, and deployment environments, we welcome community contributions in these areas in the [`/contrib`](https://github.com/spotify/backstage/tree/master/contrib) folder of the project. This is an excellent place to put things that help out the community at large, but which may not fit within the scope of the core product to support natively. Here, you will find Helm charts, alternative Docker images, and much more. +Since there is such a large landscape of possible development, build, and deployment environments, we welcome community contributions in these areas in the [`/contrib`](https://github.com/backstage/backstage/tree/master/contrib) folder of the project. This is an excellent place to put things that help out the community at large, but which may not fit within the scope of the core product to support natively. Here, you will find Helm charts, alternative Docker images, and much more. ## Write Documentation @@ -44,11 +44,11 @@ The current documentation is very limited. Help us make the `/docs` folder come We think the best way to ensure different plugins provide a consistent experience is through a solid set of reusable UI/UX components. Backstage uses [Storybook](http://backstage.io/storybook). -Either help us [create new components](https://github.com/spotify/backstage/labels/help%20wanted) or improve stories for the existing ones (look for files with `*.stories.tsx`). +Either help us [create new components](https://github.com/backstage/backstage/labels/help%20wanted) or improve stories for the existing ones (look for files with `*.stories.tsx`). ## Submit Feedback -The best way to send feedback is to file [an issue](https://github.com/spotify/backstage/issues). +The best way to send feedback is to file [an issue](https://github.com/backstage/backstage/issues). If you are proposing a feature: @@ -74,7 +74,7 @@ All code is formatted with `prettier` using the configuration in the repo. If po If you're contributing to the backend or CLI tooling, be mindful of cross-platform support. [This](https://shapeshed.com/writing-cross-platform-node/) blog post is a good guide of what to keep in mind when writing cross-platform NodeJS. -Also be sure to skim through our [ADRs](https://github.com/spotify/backstage/tree/master/docs/architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](https://github.com/spotify/backstage/blob/master/docs/architecture-decisions/adr006-avoid-react-fc.md) is one to look out for. +Also be sure to skim through our [ADRs](https://github.com/backstage/backstage/tree/master/docs/architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](https://github.com/backstage/backstage/blob/master/docs/architecture-decisions/adr006-avoid-react-fc.md) is one to look out for. If there are any updates in `markdown` file please make sure to run `yarn run lint:docs`. Though it is checked on `lint-staged`. It is required to install [vale](https://docs.errata.ai/vale/install) separately and make sure it is accessed by global command. @@ -97,7 +97,7 @@ For more information, checkout [adding a changeset](https://github.com/atlassian This project adheres to the [Spotify FOSS Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code. -[code-of-conduct]: https://github.com/spotify/backstage/blob/master/CODE_OF_CONDUCT.md +[code-of-conduct]: https://github.com/backstage/backstage/blob/master/CODE_OF_CONDUCT.md # Security Issues? diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000000..19bbb3bcb9 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,52 @@ +# Backstage Governance + +This document defines project governance for the project. + +## Maintainers + +Backstage Maintainers have write access to the Backstage GitHub repository https://github.com/backstage/backstage. The current maintainers can be found in [MAINTAINERS](MAINTAINERS.md). + +This privilege is granted with some expectation of responsibility: maintainers are people who care about the Backstage project and want to help it grow and improve. A maintainer is not just someone who can make changes, but someone who has demonstrated his or her ability to collaborate with the team, get the most knowledgeable people to review code, contribute high-quality code, and follow through to fix issues (in code or tests). + +A maintainer is a contributor to the Backstage project's success and a citizen helping the project succeed. + +## Becoming a Maintainer + +To become a maintainer you need to demonstrate the following: + +- commitment to the project + - participate in discussions, contributions, code reviews for 3 months or more, + - perform code reviews for 10 non-trivial pull requests, + - contribute 10 non-trivial pull requests and have them merged into master, +- ability to write good code, +- ability to collaborate with the team, +- understanding of how the team works (policies, processes for testing and code review, etc), +- understanding of the project's code base and coding style. + +## Changes in Maintainership + +A new maintainer must be proposed by an existing maintainer by opening an issue (with title `Maintainer Nomination`) to the Backstage GitHub repository (https://github.com/backstage/backstage) containing the following information: + +- nominee's first and last name, +- nominee's email address and GitHub user name, +- an explanation of why the nominee should be a maintainer, +- a list of links to non-trivial pull requests (top 10) authored by the nominee. + +Maintainers can be removed by a 2/3 majority vote. + +## Approving PRs + +PRs may be merged after receiving at least one approval from a maintainer. + +## GitHub Project Administration + +Maintainers will be added to the collaborators list of the Backstage repository with "Write" access. + +## Changes in Governance + +All changes in Governance require a 2/3 majority vote. + +## Other Changes + +Unless specified above, all other changes to the project require a 2/3 majority vote. +Additionally, any maintainer may request that any change require a 2/3 majority vote. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000000..33437692c9 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,21 @@ +# Maintainers + +- See [CONTRIBUTING.md](CONTRIBUTING.md) for general contribution guidelines. + +## Current Maintainers 🏓 + +- Stefan Ålund - Spotify (GitHub: @stefanalund, Discord: @stalund) +- Patrik Oldsberg - Spotify (GitHub: @Rugvip, Discord: @Rugvip) +- Fredrik Adelöw - Spotify (GitHub: @freben, Discord: @freben) +- Ben Lambert - Spotify (GitHub: @benjdlambert, Discord: @blam) + +## Plugin maintainers 🧩 + +Teams and individuals that maintain a plugin (or another non-core module of the code) can get write access to that part of the repo using CODEOWNERS. + +## Hall of Fame 👏 + +People that have made significant contributions to the project and earned write access: + +- Andrew Thauer - Wealthsimple (GitHub: @andrewthauer) +- Oliver Sand - SDA SE (GitHub: @Fox32) diff --git a/OWNERS.md b/OWNERS.md deleted file mode 100644 index 1e7fe5b774..0000000000 --- a/OWNERS.md +++ /dev/null @@ -1,19 +0,0 @@ -# Owners - -- See [CONTRIBUTING.md](CONTRIBUTING.md) for general contribution guidelines. - -## Maintainers 🏓 - -- Patrik Oldsberg (@Rugvip, Spotify) -- Fredrik Adelöw (@freben, Spotify) -- Raghunandan Balachandran (@soapraj, Spotify) -- Ben Lambert (@benjdlambert, Spotify) -- Marcus Eide (@marcuseide, Spotify) -- Niklas Ek (@nikek, Spotify) -- Stefan Ålund (@stefanalund, Spotify) -- Kat Zhou (@katz95, Spotify) - -## Hall of Fame 👏 - -- Andrew Thauer (@andrewthauer, Wealthsimple) -- Oliver Sand (@Fox32, SDA-SE) diff --git a/README.md b/README.md index 70badd5321..a4b21539b5 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,15 @@ [![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/spotify/backstage/workflows/Main%20Master%20Build/badge.svg)](https://github.com/spotify/backstage/actions?query=workflow%3A%22Main+Master+Build%22) +[![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) [![Discord](https://img.shields.io/discord/687207715902193673)](https://discord.gg/EBHEGzX) ![Code style](https://img.shields.io/badge/code_style-prettier-ff69b4.svg) -[![Codecov](https://img.shields.io/codecov/c/github/spotify/backstage)](https://codecov.io/gh/spotify/backstage) -[![](https://img.shields.io/npm/v/@backstage/core?label=Version)](https://github.com/spotify/backstage/releases) +[![Codecov](https://img.shields.io/codecov/c/github/backstage/backstage)](https://codecov.io/gh/backstage/backstage) +[![](https://img.shields.io/npm/v/@backstage/core?label=Version)](https://github.com/backstage/backstage/releases) + +> We recently moved from `spotify/backstage`, update your remotes! +> +> `git remote set-url origin git@github.com:backstage/backstage.git` ## What is Backstage? @@ -23,7 +27,7 @@ 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 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/spotify/backstage/tree/master/plugins) that further expand Backstage’s customizability and functionality +- Plus, a growing ecosystem of [open source plugins](https://github.com/backstage/backstage/tree/master/plugins) that further expand Backstage’s customizability and functionality Backstage was created by Spotify but is now hosted by the [Cloud Native Computing Foundation (CNCF)](https://www.cncf.io) as a Sandbox level project. Read the announcement [here](https://backstage.io/blog/2020/09/23/backstage-cncf-sandbox). @@ -46,8 +50,8 @@ Check out [the documentation](https://backstage.io/docs/getting-started) on how ## Community - [Discord chatroom](https://discord.gg/MUpMjP2) - Get support or discuss the project -- [Good First Issues](https://github.com/spotify/backstage/contribute) - Start here if you want to contribute -- [RFCs](https://github.com/spotify/backstage/labels/rfc) - Help shape the technical direction +- [Good First Issues](https://github.com/backstage/backstage/contribute) - Start here if you want to contribute +- [RFCs](https://github.com/backstage/backstage/labels/rfc) - Help shape the technical direction - [FAQ](https://backstage.io/docs/FAQ) - Frequently Asked Questions - [Code of Conduct](CODE_OF_CONDUCT.md) - This is how we roll - [Adopters](ADOPTERS.md) - Companies already using Backstage diff --git a/app-config.development.yaml b/app-config.development.yaml deleted file mode 100644 index 817847c6d6..0000000000 --- a/app-config.development.yaml +++ /dev/null @@ -1,13 +0,0 @@ -app: - baseUrl: http://localhost:3000 - -backend: - baseUrl: http://localhost:7000 - listen: - port: 7000 - cors: - origin: http://localhost:3000 - methods: [GET, POST, PUT, DELETE] - credentials: true - csp: - connect-src: ["'self'", 'http:', 'https:'] diff --git a/app-config.yaml b/app-config.yaml index fbeba50835..395adfc44a 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -1,6 +1,6 @@ app: title: Backstage Example App - baseUrl: http://localhost:7000 + baseUrl: http://localhost:3000 googleAnalyticsTrackingId: # UA-000000-0 backend: @@ -10,8 +10,13 @@ backend: database: client: sqlite3 connection: ':memory:' + cors: + origin: http://localhost:3000 + methods: [GET, POST, PUT, DELETE] + credentials: true csp: - connect-src: ["'self'", 'https:'] + connect-src: ["'self'", 'http:', 'https:'] + # workingDirectory: /tmp # Use this to configure a working directory for the scaffolder, defaults to the OS temp-dir # See README.md in the proxy-backend plugin for information on the configuration format proxy: @@ -47,6 +52,12 @@ proxy: Authorization: $env: PAGERDUTY_TOKEN + '/buildkite/api': + target: https://api.buildkite.com/v2/ + headers: + Authorization: + $env: BUILDKITE_TOKEN + organization: name: My Company @@ -139,23 +150,25 @@ catalog: locations: # Backstage example components - type: url - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/all-components.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all-components.yaml # Example component for github-actions - type: url - target: https://github.com/spotify/backstage/blob/master/plugins/github-actions/examples/sample.yaml + target: https://github.com/backstage/backstage/blob/master/plugins/github-actions/examples/sample.yaml # Example component for techdocs - type: url - target: https://github.com/spotify/backstage/blob/master/plugins/techdocs-backend/examples/documented-component/documented-component.yaml + target: https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend/examples/documented-component/documented-component.yaml # Backstage example APIs - type: url - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/all-apis.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all-apis.yaml # Backstage example templates - type: url - target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/all-templates.yaml + target: https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/sample-templates/all-templates.yaml + # Backstage example groups and users + - type: url + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/acme-corp.yaml scaffolder: github: - host: https://github.com token: $env: GITHUB_TOKEN visibility: public # or 'internal' or 'private' @@ -231,6 +244,14 @@ auth: $env: AUTH_MICROSOFT_CLIENT_SECRET tenantId: $env: AUTH_MICROSOFT_TENANT_ID + onelogin: + development: + clientId: + $env: AUTH_ONELOGIN_CLIENT_ID + clientSecret: + $env: AUTH_ONELOGIN_CLIENT_SECRET + issuer: + $env: AUTH_ONELOGIN_ISSUER costInsights: engineerCost: 200000 products: @@ -244,7 +265,7 @@ costInsights: name: Cloud Storage icon: storage bigQuery: - name: Big Query + name: BigQuery icon: search metrics: DAU: diff --git a/catalog-info.yaml b/catalog-info.yaml index 405c3f31b4..617d01093e 100644 --- a/catalog-info.yaml +++ b/catalog-info.yaml @@ -5,10 +5,10 @@ metadata: description: | Backstage is an open-source developer portal that puts the developer experience first. annotations: - github.com/project-slug: spotify/backstage - backstage.io/techdocs-ref: github:https://github.com/spotify/backstage.git + github.com/project-slug: backstage/backstage + backstage.io/techdocs-ref: github:https://github.com/backstage/backstage.git lighthouse.com/website-url: https://backstage.io spec: type: library - owner: Spotify + owner: CNCF lifecycle: experimental diff --git a/contrib/chart/backstage/Chart.yaml b/contrib/chart/backstage/Chart.yaml index 24c6f2a4d7..8aeab9be3e 100644 --- a/contrib/chart/backstage/Chart.yaml +++ b/contrib/chart/backstage/Chart.yaml @@ -1,6 +1,6 @@ apiVersion: v2 name: backstage -description: A Helm chart for Spotify Backstage +description: A Helm chart for Backstage type: application # This is the chart version. This version number should be incremented each time you make changes @@ -12,7 +12,7 @@ version: 0.1.1 appVersion: v0.1.1-alpha.23 sources: - - https://github.com/spotify/backstage + - https://github.com/backstage/backstage - https://github.com/spotify/lighthouse-audit-service dependencies: diff --git a/contrib/chart/backstage/README.md b/contrib/chart/backstage/README.md index 9d1c93765b..96bfdb4351 100644 --- a/contrib/chart/backstage/README.md +++ b/contrib/chart/backstage/README.md @@ -7,7 +7,7 @@ This folder contains Helm charts that can easily create a Kubernetes deployment These charts depend on the `nginx-ingress` controller being present in the cluster. If it's not already installed you can run: -``` +```shell helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx helm install nginx-ingress ingress-nginx/ingress-nginx ``` @@ -16,7 +16,7 @@ helm install nginx-ingress ingress-nginx/ingress-nginx After choosing a DNS name where backstage will be hosted create a yaml file for your custom configuration. -``` +```yaml appConfig: app: baseUrl: https://backstage.mydomain.com @@ -30,13 +30,12 @@ appConfig: techdocs: storageUrl: https://backstage.mydomain.com/api/techdocs/static/docs requestUrl: https://backstage.mydomain.com/api/techdocs - ``` Then use it to run: -``` -git clone https://github.com/spotify/backstage.git +```shell +git clone https://github.com/backstage/backstage.git cd contrib/chart/backstage helm dependency update helm install -f backstage-mydomain.yaml backstage . @@ -54,7 +53,7 @@ After a few minutes Backstage should be up and running in your cluster under the Make sure to create the appropriate DNS entry in your infrastructure. To find the public IP address run: -```bash +```shell $ kubectl get ingress NAME HOSTS ADDRESS PORTS AGE backstage-ingress * 123.1.2.3 80 17m @@ -74,10 +73,10 @@ These charts can install or reuse a `clusterIssuer` to generate certificates for To enable it you need to provide a valid email address in the chart's values: -``` +```yaml issuer: email: me@example.com - clusterIssuer: "letsencrypt-prod" + clusterIssuer: 'letsencrypt-prod' ``` By default, the charts use `letsencrypt-staging` so in the above example we instruct helm to use the production issuer @@ -92,7 +91,7 @@ Configuring a connection to an existing PostgreSQL instance is possible through First create a yaml file with the configuration you want to override, for example `backstage-prod.yaml`: -```bash +```yaml postgresql: enabled: false @@ -122,18 +121,19 @@ lighthouse: user: password: database: lighthouse_audit_service - ``` -For the CA, create a `configMap` named `-postgres-ca` with a file called `ca.crt`: +For the CA, create a `configMap` named `--postgres-ca` with a file called `ca.crt`: +```shell +kubectl create configmap my-company-backstage-postgres-ca --from-file=ca.crt" ``` -kubectl create configmap my-backstage --from-file=ca.crt" -``` + +> Where the release name contains the chart name "backstage" then only the release name will be used. Now install the helm chart: -``` +```shell cd contrib/chart/backstage helm install -f backstage-prod.yaml my-backstage . ``` @@ -142,7 +142,7 @@ helm install -f backstage-prod.yaml my-backstage . The docker images used for the deployment can be configured through the charts values: -``` +```yaml frontend: image: repository: @@ -155,15 +155,31 @@ backend: lighthouse: image: - repository: tag: ``` +### Use a private docker repo + +Create a docker-registry secret + +```shell +kubectl create secret docker-registry # args +``` + +> For private images on docker hub --docker-server can be set to docker.io + +Reference the secret in your chart values + +```yaml +dockerRegistrySecretName: +``` + ### Different namespace To install the charts a specific namespace use `--namespace `: -``` +```shell helm install -f my_values.yaml --namespace demos backstage . ``` @@ -171,7 +187,7 @@ helm install -f my_values.yaml --namespace demos backstage . To deploy backstage with the pre-loaded demo data disable `backend.demoData`: -``` +```shell helm install -f my_values.yaml --set backend.demoData=false backstage . ``` @@ -226,7 +242,7 @@ This error happens in the backend when it tries to connect to the configured Pos To uninstall Backstage simply run: -``` +```shell RELEASE_NAME= # use `helm list` to find out the name helm uninstall ${RELEASE_NAME} kubectl delete pvc data-${RELEASE_NAME}-postgresql-0 diff --git a/contrib/chart/backstage/files/app-config.development.yaml.tpl b/contrib/chart/backstage/files/app-config.development.yaml.tpl index 76d6499145..1e0a41ad63 100644 --- a/contrib/chart/backstage/files/app-config.development.yaml.tpl +++ b/contrib/chart/backstage/files/app-config.development.yaml.tpl @@ -18,19 +18,19 @@ catalog: locations: # Backstage example components - type: github - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/all-components.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all-components.yaml # Example component for github-actions - type: github - target: https://github.com/spotify/backstage/blob/master/plugins/github-actions/examples/sample.yaml + target: https://github.com/backstage/backstage/blob/master/plugins/github-actions/examples/sample.yaml # Example component for techdocs - type: github - target: https://github.com/spotify/backstage/blob/master/plugins/techdocs-backend/examples/documented-component/documented-component.yaml + target: https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend/examples/documented-component/documented-component.yaml # Backstage example APIs - type: github - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/all-apis.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/all-apis.yaml # Backstage example templates - type: github - target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/all-templates.yaml + target: https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/sample-templates/all-templates.yaml {{- else }} locations: [] {{- end }} diff --git a/contrib/chart/backstage/templates/backend-deployment.yaml b/contrib/chart/backstage/templates/backend-deployment.yaml index c57764db8e..99ec955242 100644 --- a/contrib/chart/backstage/templates/backend-deployment.yaml +++ b/contrib/chart/backstage/templates/backend-deployment.yaml @@ -20,6 +20,10 @@ spec: component: backend spec: + {{- if .Values.dockerRegistrySecretName }} + imagePullSecrets: + - name: {{ .Values.dockerRegistrySecretName }} + {{- end}} containers: - name: {{ .Chart.Name }}-backend image: {{ .Values.backend.image.repository }}:{{ .Values.backend.image.tag }} diff --git a/contrib/chart/backstage/templates/backend-secret.yaml b/contrib/chart/backstage/templates/backend-secret.yaml index dc65f5777a..b340f39d7c 100644 --- a/contrib/chart/backstage/templates/backend-secret.yaml +++ b/contrib/chart/backstage/templates/backend-secret.yaml @@ -19,4 +19,5 @@ stringData: GITLAB_TOKEN: {{ .Values.auth.gitlabToken }} AZURE_TOKEN: {{ .Values.auth.azure.api.token }} NEW_RELIC_REST_API_KEY: {{ .Values.auth.newRelicRestApiKey }} + TRAVISCI_AUTH_TOKEN: {{ .Values.auth.travisciAuthToken }} {{- end }} diff --git a/contrib/chart/backstage/templates/frontend-deployment.yaml b/contrib/chart/backstage/templates/frontend-deployment.yaml index a5d84be2b2..5430ef041f 100644 --- a/contrib/chart/backstage/templates/frontend-deployment.yaml +++ b/contrib/chart/backstage/templates/frontend-deployment.yaml @@ -20,6 +20,10 @@ spec: component: frontend spec: + {{- if .Values.dockerRegistrySecretName }} + imagePullSecrets: + - name: {{ .Values.dockerRegistrySecretName }} + {{- end}} containers: - name: {{ .Chart.Name }}-frontend image: {{ .Values.frontend.image.repository }}:{{ .Values.frontend.image.tag }} diff --git a/contrib/chart/backstage/templates/lighthouse-deployment.yaml b/contrib/chart/backstage/templates/lighthouse-deployment.yaml index 70341a2a22..13bb8eadbb 100644 --- a/contrib/chart/backstage/templates/lighthouse-deployment.yaml +++ b/contrib/chart/backstage/templates/lighthouse-deployment.yaml @@ -21,6 +21,10 @@ spec: component: lighthouse-audit-service spec: + {{- if .Values.dockerRegistrySecretName }} + imagePullSecrets: + - name: {{ .Values.dockerRegistrySecretName }} + {{- end}} containers: - name: lighthouse-audit-service image: {{ .Values.lighthouse.image.repository }}:{{ .Values.lighthouse.image.tag }} diff --git a/contrib/chart/backstage/templates/postgresql-password-secret.yaml b/contrib/chart/backstage/templates/postgresql-password-secret.yaml index 9685130a03..e53369adb9 100644 --- a/contrib/chart/backstage/templates/postgresql-password-secret.yaml +++ b/contrib/chart/backstage/templates/postgresql-password-secret.yaml @@ -8,7 +8,7 @@ metadata: labels: release: {{ .Release.Name }} annotations: - "helm.sh/hook": "pre-install" + "helm.sh/hook": "pre-install,pre-upgrade" "helm.sh/hook-delete-policy": "before-hook-creation" data: postgresql-password: {{ .Values.appConfig.backend.database.connection.password | b64enc }} @@ -23,7 +23,7 @@ metadata: labels: release: {{ .Release.Name }} annotations: - "helm.sh/hook": "pre-install" + "helm.sh/hook": "pre-install,pre-upgrade" "helm.sh/hook-delete-policy": "before-hook-creation" data: postgresql-password: {{ .Values.lighthouse.database.connection.password | b64enc }} diff --git a/contrib/chart/backstage/values.yaml b/contrib/chart/backstage/values.yaml index f92e8aad47..a4a0fadcc2 100644 --- a/contrib/chart/backstage/values.yaml +++ b/contrib/chart/backstage/values.yaml @@ -105,14 +105,14 @@ appConfig: rejectUnauthorized: false ca: sentry: - organization: spotify + organization: example-org-name techdocs: storageUrl: https://demo.example.com/api/techdocs/static/docs requestUrl: https://demo.example.com/api/techdocs lighthouse: baseUrl: https://demo.example.com/lighthouse-api rollbar: - organization: roadie + organization: example-org-name # Auth config has recently moved into the app config file in upstream Backstage. However, # most of this config simply mandates that items like the client id and client secret should @@ -249,3 +249,4 @@ auth: githubToken: g gitlabToken: g newRelicRestApiKey: r + travisciAuthToken: fake-travis-ci-auth-token diff --git a/contrib/docker/kubernetes-example-backend/Dockerfile b/contrib/docker/kubernetes-example-backend/Dockerfile index df617decf5..b7d7a9631e 100644 --- a/contrib/docker/kubernetes-example-backend/Dockerfile +++ b/contrib/docker/kubernetes-example-backend/Dockerfile @@ -30,6 +30,4 @@ RUN yarn install --frozen-lockfile --production # Do not use this Dockerfile outside of that command, as it will copy in the source code instead. COPY . . -CMD ["node", "packages/backend"] - - +CMD ["node", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.development.yaml"] diff --git a/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md b/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md new file mode 100644 index 0000000000..f5288cf144 --- /dev/null +++ b/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md @@ -0,0 +1,58 @@ +# Running the backend behind a Corporate Proxy + +Let's admit it, we've all been there. Sometimes you've gotta run stuff with no way out to the public internet, only the smallest of corporate proxy tunnels. + +Whilst this isn't supported natively by Backstage, this might help you get your installation up and running making calls through the said proxy tunnel. + +Unfortunately, `nodejs` does not respect `HTTP(S)_PROXY` environment variables by default, and the library that we use to provide `fetch` functionality `node-fetch` (provided by `cross-fetch`) does not also respect these environment variables. + +There are however some ways to get this to work without too much effort. It's most likely that you're going to run into these issues from the `backend` part of `backstage` as that's the part that isn't helped by your browser or OS's settings for the corporate proxy. + +**Note:** You're gonna want to be in your backend working directory for these solutions as that's where the requests come from that don't go through this proxy. + +### Using `global-agent` + +1. Install `global-agent` using `yarn add global-agent` +2. Go to the entry file for the backend (`src/index.ts`) +3. At the top of the file paste the following: + +```ts +import 'global-agent/bootstrap'; +``` + +4. Start the backend with the `global-agent` variables + +```sh +export GLOBAL_AGENT_HTTP_PROXY=$HTTP_PROXY +yarn start +``` + +More information and more options for configuring `global-agent` including just using the default environment variables can be found here: https://github.com/gajus/global-agent + +### Using `proxy-agent` + +`proxy-agent` is a library that you can use to override the `globalAgents` of `node` land with a tunnel to use for each request. + +1. Install `proxy-agent` using `yarn add proxy-agent` +2. Go to the entry file for the backend (`src/index.ts`) +3. At the top of the file paste the following: + +```ts +import ProxyAgent from 'proxy-agent'; +import http from 'http'; +import https from 'https'; + +/* + Something to note here, this might need different configuration depending on your own setup. + If you only have an http_proxy then you'll need to set that as both the http and https globalAgent instead. +*/ +if (process.env.HTTP_PROXY) { + http.globalAgent = new ProxyAgent(process.env.HTTP_PROXY); +} + +if (process.env.HTTPS_PROXY) { + https.globalAgent = new ProxyAgent(process.env.HTTPS_PROXY); +} +``` + +4. Start the backend with `yarn start` diff --git a/contrib/kubernetes/basic_kubernetes_example_with_helm/backstage/Chart.yaml b/contrib/kubernetes/basic_kubernetes_example_with_helm/backstage/Chart.yaml index efc3635a7f..6cbb7ea3cb 100644 --- a/contrib/kubernetes/basic_kubernetes_example_with_helm/backstage/Chart.yaml +++ b/contrib/kubernetes/basic_kubernetes_example_with_helm/backstage/Chart.yaml @@ -1,5 +1,5 @@ apiVersion: v1 appVersion: '1.0' -description: A Helm chart for Spotify Backstage +description: A Helm chart for Backstage name: backstage version: 0.1.1-alpha.12 diff --git a/contrib/kubernetes/plain_single_backend_deplyoment/README.md b/contrib/kubernetes/plain_single_backend_deployment/README.md similarity index 97% rename from contrib/kubernetes/plain_single_backend_deplyoment/README.md rename to contrib/kubernetes/plain_single_backend_deployment/README.md index 685bed92a5..48c3490f81 100644 --- a/contrib/kubernetes/plain_single_backend_deplyoment/README.md +++ b/contrib/kubernetes/plain_single_backend_deployment/README.md @@ -13,7 +13,7 @@ yarn install yarn docker-build -kubectl apply -f contrib/kubernetes/plain_single_backend_deplyoment/deployment.yaml +kubectl apply -f contrib/kubernetes/plain_single_backend_deployment/deployment.yaml ``` You can use the following commands to monitor the deployment: diff --git a/contrib/kubernetes/plain_single_backend_deplyoment/deployment.yaml b/contrib/kubernetes/plain_single_backend_deployment/deployment.yaml similarity index 75% rename from contrib/kubernetes/plain_single_backend_deplyoment/deployment.yaml rename to contrib/kubernetes/plain_single_backend_deployment/deployment.yaml index 87dee94895..25c9207438 100644 --- a/contrib/kubernetes/plain_single_backend_deplyoment/deployment.yaml +++ b/contrib/kubernetes/plain_single_backend_deployment/deployment.yaml @@ -28,6 +28,9 @@ spec: image: example-backend:latest imagePullPolicy: Never + command: [node, packages/backend] + args: [--config, app-config.yaml, --config, k8s-config.yaml] + env: # We set this to development to make the backend start with incomplete configuration. In a production # deployment you will want to make sure that you have a full configuration, and remove any plugins that @@ -35,16 +38,12 @@ spec: - name: NODE_ENV value: development - # This makes us load in `app-config.production.yaml` if there is one. - - name: APP_ENV - value: production - - # This makes it possible for the app to reach the backend when serving through `kubectl proxy` - # If you expose the service using for example an ingress controller, you should - # switch this out or remove it. - # - # Note that we're not setting app.baseUrl here, as setting the base path is not working at the moment. - # Further work is needed around the routing in the frontend or react-router before we can support that. + # This makes it possible for the app to reach the backend when serving through `kubectl proxy` + # If you expose the service using for example an ingress controller, you should + # switch this out or remove it. + # + # Note that we're not setting app.baseUrl here, as setting the base path is not working at the moment. + # Further work is needed around the routing in the frontend or react-router before we can support that. - name: APP_CONFIG_backend_baseUrl value: http://localhost:8001/api/v1/namespaces/backstage/services/backstage-backend:http/proxy @@ -54,8 +53,8 @@ spec: volumeMounts: - name: config-volume - mountPath: /usr/src/app/app-config.local.yaml - subPath: app-config.local.yaml + mountPath: /usr/src/app/k8s-config.yaml + subPath: k8s-config.yaml resources: limits: @@ -77,7 +76,7 @@ spec: name: backstage-config items: - key: app-config - path: app-config.local.yaml + path: k8s-config.yaml --- apiVersion: v1 kind: ConfigMap diff --git a/docs/FAQ.md b/docs/FAQ.md index 7163d955c7..7b906a341b 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -48,11 +48,11 @@ source candidates. (And we'll probably end up writing some brand new ones, too.) ### What's the roadmap for Backstage? We envision three phases, which you can learn about in -[our project roadmap](https://github.com/spotify/backstage#project-roadmap). +[our project roadmap](https://github.com/backstage/backstage#project-roadmap). Even though the open source version of Backstage is relatively new compared to our internal version, we have already begun work on various aspects of all three phases. Looking at the -[milestones for active issues](https://github.com/spotify/backstage/milestones) +[milestones for active issues](https://github.com/backstage/backstage/milestones) will also give you a sense of our progress. ### My company doesn't have thousands of developers or services. Is Backstage overkill? @@ -87,8 +87,8 @@ well-known tech and a large flora of components. ### What technology does Backstage use? The codebase is a large-scale React application that uses TypeScript. For -[Phase 2](https://github.com/spotify/backstage#project-roadmap), we plan to use -Node.js and GraphQL. +[Phase 2](https://github.com/backstage/backstage#project-roadmap), we plan to +use Node.js and GraphQL. ### What is the end-to-end user flow? The happy path story. @@ -116,7 +116,7 @@ components. Plugins can fetch data either from the backend or an API exposed through the proxy. Learn more about -[the different components](https://github.com/spotify/backstage#overview) that +[the different components](https://github.com/backstage/backstage#overview) that make up Backstage. ### Do I have to write plugins in TypeScript? @@ -127,10 +127,10 @@ APIs in TypeScript, but aren't forcing it on individual plugins. ### How do I find out if a plugin already exists? Before you write a plugin, -[search the plugin issues](https://github.com/spotify/backstage/issues?q=is%3Aissue+label%3Aplugin+) +[search the plugin issues](https://github.com/backstage/backstage/issues?q=is%3Aissue+label%3Aplugin+) to see if it already exists or is in the works. If no one's thought of it yet, great! Open a new issue as -[a plugin suggestion](https://github.com/spotify/backstage/issues/new/choose) +[a plugin suggestion](https://github.com/backstage/backstage/issues/new/choose) and describe what your plugin will do. This will help coordinate our contributors' efforts and avoid duplicating existing functionality. @@ -151,7 +151,7 @@ above) ### Are you planning to have plugins baked into the repo? Or should they be developed in separate repos? Contributors can add open source plugins to the plugins directory in -[this monorepo](https://github.com/spotify/backstage). Integrators can then +[this monorepo](https://github.com/backstage/backstage). Integrators can then configure which open source plugins are available to use in their instance of the app. Open source plugins are downloaded as npm packages published in the open source repository. While we encourage using the open source model, we know @@ -166,7 +166,7 @@ We chose GitHub because it is the tool that we are most familiar with, so that will naturally lead to integrations for GitHub being developed at an early stage. Hosting this project on GitHub does not exclude integrations with alternatives, such as -[GitLab](https://github.com/spotify/backstage/issues?q=is%3Aissue+is%3Aopen+GitLab) +[GitLab](https://github.com/backstage/backstage/issues?q=is%3Aissue+is%3Aopen+GitLab) or Bitbucket. We believe that in time there will be plugins that will provide functionality for these tools as well. Hopefully, contributed by the community! Also note, implementations of Backstage can be hosted wherever you feel suits @@ -215,17 +215,17 @@ data is shared with. Yes. The core frontend framework could be used for building any large-scale web application where (1) multiple teams are building separate parts of the app, and (2) you want the overall experience to be consistent. That being said, in -[Phase 2](https://github.com/spotify/backstage#project-roadmap) of the project +[Phase 2](https://github.com/backstage/backstage#project-roadmap) of the project we will add features that are needed for developer portals and systems for managing software ecosystems. Our ambition will be to keep Backstage modular. ### How can I get involved? Jump right in! Come help us fix some of the -[early bugs and first issues](https://github.com/spotify/backstage/labels/good%20first%20issue) -or reach [a new milestone](https://github.com/spotify/backstage/milestones). Or -write an open source plugin for Backstage, like this -[Lighthouse plugin](https://github.com/spotify/backstage/tree/master/plugins/lighthouse). +[early bugs and first issues](https://github.com/backstage/backstage/labels/good%20first%20issue) +or reach [a new milestone](https://github.com/backstage/backstage/milestones). +Or write an open source plugin for Backstage, like this +[Lighthouse plugin](https://github.com/backstage/backstage/tree/master/plugins/lighthouse). See all the ways you can -[contribute here](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md). +[contribute here](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md). We'd love to have you as part of the community. diff --git a/docs/api/utility-apis.md b/docs/api/utility-apis.md index 1ebf2ae88b..2547db5c5c 100644 --- a/docs/api/utility-apis.md +++ b/docs/api/utility-apis.md @@ -11,7 +11,7 @@ possible residing within the plugin itself and its backend APIs. There will however always be a need for plugins to communicate outside of its boundaries, both with other plugins and the app itself. -Backstage provides two primary methods for plugins to communication across their +Backstage provides two primary methods for plugins to communicate across their boundaries in client-side code. The first one being the `createPlugin` API and the registration hooks passed to the `register` method, and the second one being Utility APIs. While the `createPlugin` API is focused on the initialization @@ -22,7 +22,7 @@ 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 create using `createApiRef`, which is +reference Utility APIs. `ApiRef`s are created using `createApiRef`, which is exported by `@backstage/core`. 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 @@ -160,7 +160,8 @@ const app = createApp({ ``` A common pattern is to export a list of all APIs from `apis.ts`, next to -`App.tsx`. See the [example app in this repo](../../packages/app/src/apis.ts) +`App.tsx`. See the +[example app in this repo](https://github.com/backstage/backstage/blob/master/packages/app/src/apis.ts) for an example. ## Custom implementations of Utility APIs @@ -194,8 +195,8 @@ 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`. -Custom Utility APIs can be either public or private, which it is up to the -plugin to choose. Private APIs do not expose an external API surface, and it's +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 therefore possible to make breaking changes to the API without affecting other users of the plugin. If an API is made public however, it opens up for other plugins to make use of the API, and it also makes it possible for users for your @@ -242,7 +243,7 @@ The figure below shows the relationship between The current method for connecting Utility API providers and consumers is via the React tree using an `ApiProvider`, which is added to the `AppProvider` of the `App`. In the future there may potentially be more ways to do this, in ways that -are not tied to react. A design goal of the Utility APIs was to not have them +are not tied to React. A design goal of the Utility APIs was to not have them directly tied to React. The indirection provided by Utility APIs also makes it straightforward to test diff --git a/docs/architecture-decisions/adr002-default-catalog-file-format.md b/docs/architecture-decisions/adr002-default-catalog-file-format.md index d831581d5b..699f7af8ed 100644 --- a/docs/architecture-decisions/adr002-default-catalog-file-format.md +++ b/docs/architecture-decisions/adr002-default-catalog-file-format.md @@ -39,7 +39,7 @@ inside Backstage, or by push events from a CI/CD pipelines, or by webhook triggers from the version control system, etc. Each file describes one or more entities in accordance with the -[Backstage System Model](https://github.com/spotify/backstage/issues/390). All +[Backstage System Model](https://github.com/backstage/backstage/issues/390). All of these entities have a common structure and nomenclature, and they are stored in the software catalog from which they then can be queried. @@ -87,7 +87,7 @@ The root envelope object has the following structure. ### `apiVersion` and `kind` The `kind` is the high level entity type being described, typically from the -[Backstage system model](https://github.com/spotify/backstage/issues/390). The +[Backstage system model](https://github.com/backstage/backstage/issues/390). The first versions of the catalog will focus on the `Component` kind. The `apiVersion`is the version of specification format for that particular diff --git a/docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md b/docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md index 045588f505..68394de17c 100644 --- a/docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md +++ b/docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md @@ -41,7 +41,7 @@ worker.start(); ``` and in a more real life scenario, taken from -[CatalogClient.test.ts](https://github.com/spotify/backstage/blob/f3245c4f8f0b6b2625c4a6d5d50161b612fb4757/plugins/catalog/src/api/CatalogClient.test.ts) +[CatalogClient.test.ts](https://github.com/backstage/backstage/blob/f3245c4f8f0b6b2625c4a6d5d50161b612fb4757/plugins/catalog/src/api/CatalogClient.test.ts) ```ts beforeEach(() => { diff --git a/docs/architecture-decisions/adr008-default-catalog-file-name.md b/docs/architecture-decisions/adr008-default-catalog-file-name.md index d4716318bc..6794dc87cc 100644 --- a/docs/architecture-decisions/adr008-default-catalog-file-name.md +++ b/docs/architecture-decisions/adr008-default-catalog-file-name.md @@ -11,7 +11,7 @@ While the spec for the catalog file format is well described in to the name of the catalog file. Following discussion in -[Issue 1822](https://github.com/spotify/backstage/pull/1822#pullrequestreview-461253670), +[Issue 1822](https://github.com/backstage/backstage/pull/1822#pullrequestreview-461253670), a decision was made. ## Name diff --git a/docs/architecture-decisions/adr009-entity-references.md b/docs/architecture-decisions/adr009-entity-references.md index 8b7984ea49..a6fe3ee583 100644 --- a/docs/architecture-decisions/adr009-entity-references.md +++ b/docs/architecture-decisions/adr009-entity-references.md @@ -13,7 +13,7 @@ There was also some confusion on how to reference entities in URLs in the Backstage frontend. Following discussion in -[Issue 1947](https://github.com/spotify/backstage/issues/1947), a decision was +[Issue 1947](https://github.com/backstage/backstage/issues/1947), a decision was made. ## Entity References in YAML files diff --git a/docs/architecture-decisions/index.md b/docs/architecture-decisions/index.md index ddf2805e75..3211f37550 100644 --- a/docs/architecture-decisions/index.md +++ b/docs/architecture-decisions/index.md @@ -25,9 +25,9 @@ Records should be stored under the `architecture-decisions` directory. - Address and integrate feedback from the community - Eventually, assign a number - Add the path of the ADR to the microsite sidebar in - [`sidebars.json`](https://github.com/spotify/backstage/blob/master/microsite/sidebars.json) + [`sidebars.json`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.json) - Add the path of the ADR to the - [`mkdocs.yml`](https://github.com/spotify/backstage/blob/master/mkdocs.yml) + [`mkdocs.yml`](https://github.com/backstage/backstage/blob/master/mkdocs.yml) - Merge the pull request ## Superseding an ADR diff --git a/docs/auth/auth-backend-classes.md b/docs/auth/auth-backend-classes.md index 9dc677b439..442553d4b8 100644 --- a/docs/auth/auth-backend-classes.md +++ b/docs/auth/auth-backend-classes.md @@ -20,7 +20,7 @@ Each of these methods is hosted at an endpoint `/auth/[provider]/method`, where ``` For more information on how these methods are used and for which purpose, refer -to the documentation [here](oauth.md). +to the [OAuth documentation](oauth.md). For details on the parameters, input and output conditions for each method, refer to the type documentation under @@ -38,7 +38,7 @@ Currently OAuth is assumed to be the de facto authentication mechanism for Backstage based applications. Backstage comes with a "batteries-included" set of supported commonly used OAuth -providers: Okta, Github, Google, Gitlab, and a generic OAuth2 provider. +providers: Okta, GitHub, Google, GitLab, and a generic OAuth2 provider. All of these use the authorization flow of OAuth2 to implement authentication. diff --git a/docs/auth/index.md b/docs/auth/index.md index d7fb5d8c59..3f95efaf61 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -58,7 +58,7 @@ token used to make authenticated calls within Backstage. The middleware that will be provided by `@backstage/backend-common` allows verification of Backstage ID tokens, and optionally loading additional information about the user. The progress is tracked in -https://github.com/spotify/backstage/issues/1435. +https://github.com/backstage/backstage/issues/1435. #### Identity for App Developers diff --git a/docs/auth/oauth.md b/docs/auth/oauth.md index 178b99b153..0655175b58 100644 --- a/docs/auth/oauth.md +++ b/docs/auth/oauth.md @@ -15,10 +15,10 @@ 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/spotify/backstage/blob/master/packages/core-api/src/apis/definitions/auth.ts) +[GoogleAuthApi](https://github.com/backstage/backstage/blob/master/packages/core-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/spotify/backstage/tree/master/plugins/auth-backend) +[auth-backend](https://github.com/backstage/backstage/tree/master/plugins/auth-backend) plugin to provide a popup-based OAuth flow. ## Background @@ -58,9 +58,9 @@ easier to make authenticated requests inside a plugin. ## OAuth Flow The following describes the OAuth flow implemented by the -[auth-backend](https://github.com/spotify/backstage/tree/master/plugins/auth-backend) +[auth-backend](https://github.com/backstage/backstage/tree/master/plugins/auth-backend) and -[DefaultAuthConnector](https://github.com/spotify/backstage/blob/master/packages/core-api/src/lib/AuthConnector/DefaultAuthConnector.ts) +[DefaultAuthConnector](https://github.com/backstage/backstage/blob/master/packages/core-api/src/lib/AuthConnector/DefaultAuthConnector.ts) in `@backstage/core-api`. Component and APIs can request Access or ID Tokens from any available Auth diff --git a/docs/conf/index.md b/docs/conf/index.md index e1dfc30582..5e4639cc99 100644 --- a/docs/conf/index.md +++ b/docs/conf/index.md @@ -15,11 +15,11 @@ allowing for customization. ## Supplying Configuration -Configuration is stored in `app-config.yaml` files, with support for suffixes -such as `app-config.production.yaml` to override values for specific -environments. The configuration files themselves contain plain YAML, but with -support for loading in secrets from various sources using for example `$env` and -`$file` keys. +Configuration is stored in YAML files where the defaults are `app-config.yaml` +and `app-config.local.yaml` for local overrides. Other sets of files can by +loaded by passing `--config ` flags. The configuration files themselves +contain plain YAML, but with support for loading in secrets from various sources +using for example `$env` and `$file` keys. It is also possible to supply configuration through environment variables, for example `APP_CONFIG_app_baseUrl=https://staging.example.com`. However these @@ -28,8 +28,8 @@ development or small tweaks to be able to reuse deployment artifacts in different environments. The configuration is shared between the frontend and backend, meaning that -values that are common between the two only needs to be defined once. Such as -the `backend.baseUrl`. +values that are common between the two only need to be defined once. Such as the +`backend.baseUrl`. For more details, see [Writing Configuration](./writing.md). diff --git a/docs/conf/reading.md b/docs/conf/reading.md index a43ec8c026..6d4b61224d 100644 --- a/docs/conf/reading.md +++ b/docs/conf/reading.md @@ -117,7 +117,7 @@ The [ConfigApi](../reference/utility-apis/Config.md) in the frontend is a 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 like other APIs. See -[packages/app/src/apis.ts](https://github.com/spotify/backstage/blob/244eef851f5aa19f91c7c9b5c12d5df95cf482ca/packages/app/src/apis.ts#L66) +[packages/app/src/apis.ts](https://github.com/backstage/backstage/blob/244eef851f5aa19f91c7c9b5c12d5df95cf482ca/packages/app/src/apis.ts#L66) for an example of how this wiring is done. For standalone plugin setups in `dev/index.ts`, register a factory with a @@ -129,4 +129,4 @@ from `@backstage/core`. In backend plugins the configuration is passed in via options from the main backend package. See for example -[packages/backend/src/plugins/auth.ts](https://github.com/spotify/backstage/blob/244eef851f5aa19f91c7c9b5c12d5df95cf482ca/packages/backend/src/plugins/auth.ts#L23). +[packages/backend/src/plugins/auth.ts](https://github.com/backstage/backstage/blob/244eef851f5aa19f91c7c9b5c12d5df95cf482ca/packages/backend/src/plugins/auth.ts#L23). diff --git a/docs/conf/writing.md b/docs/conf/writing.md index bb4d0beb75..6b60c015ae 100644 --- a/docs/conf/writing.md +++ b/docs/conf/writing.md @@ -19,7 +19,7 @@ backend: baseUrl: http://localhost:7000 organization: - name: Spotify + name: CNCF proxy: /my/api: @@ -55,20 +55,28 @@ picked up by the serve tasks of `@backstage/cli` for local development, and are injected by the entrypoint of the nginx container serving the frontend in a production build. -## File Resolution +## Configuration Files It is possible to have multiple configuration files, both to support different environments, but also to define configuration that is local to specific -packages. +packages. The configuration files to load are selected using a `--config ` +flag, and it is possible to load any number of files. Paths are relative to the +working directory of the executed process, for example `package/backend`. This +means that to select a config file in the repo root when running the backend, +you would use `--config ../../my-config.yaml`. -All `app-config.yaml` files inside the monorepo root and package root are -considered, as are files with additional `local` and environment affixes such as -`development`, for example `app-config.local.yaml`, -`app-config.production.yaml`, and `app-config.development.local.yaml`. Which -environment config files are loaded is determined by the `APP_ENV` environment -variable, or `NODE_ENV` if it is not set. Local configuration files are always -loaded, but are meant for local development overrides and should typically be -`.gitignore`'d. +If no `config` flags are specified, the default behavior is to load +`app-config.yaml` and, if it exists, `app-config.local.yaml` from the repo root. +In the provided project setup, `app-config.local.yaml` is `.gitignore`'d, making +it a good place to add config overrides and secrets for local development. + +Note that if any config flags are provided, the default `app-config.yaml` files +are NOT loaded. To include them you need to explicitly include them with a flag, +for example: + +```shell +yarn start --config ../../app-config.yaml --config ../../app-config.staging.yaml +``` All loaded configuration files are merged together using the following rules: @@ -84,15 +92,15 @@ order: - Configuration from the `APP_CONFIG_` environment variables has the highest priority, followed by files. -- Files inside package directories have higher priority than those in the root - directory. -- Files with environment affixes have higher priority than ones without. -- Files with the `local` affix have higher priority than ones without. +- Files loaded with config flags are ordered by priority, where the last flag + has the highest priority. +- If no config flags are provided, `app-config.local.yaml` has higher priority + than `app-config.yaml`. ## Secrets -Secrets are supported via a special secret keys that are prefixed with `$`, -which in turn provides a number of different ways to read in secrets. To load a +Secrets are supported via special secret keys that are prefixed with `$`, which +in turn provide a number of different ways to read in secrets. To load a configuration value as a secret, supply an object with one of the special secret keys, for example `$env` or `$file`. A full list of supported secret keys can be found below. For example, the following will read the config key @@ -147,8 +155,11 @@ used to point to a specific value inside the file. Supported file extensions are ```yaml $data: ./my-secrets.json#deployment.key +``` -# my-secrets.json +Example `my-secrets.json` file: + +```json { "deployment": { "key": "my-secret-key" diff --git a/docs/dls/design.md b/docs/dls/design.md index fa3a0c159e..3bf283b77f 100644 --- a/docs/dls/design.md +++ b/docs/dls/design.md @@ -46,9 +46,9 @@ referencing Figma documents to share specs and prototypes with the community. ### Creating a New Design Component -| Step 1 | Step 2 | Step 3 | Step 4 | Step 5 | Step 6 | -| :------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- | -| Platform design team submits an issue to **spotify/Backstage GitHub** with a potential component. | Backstage community offers feedback or approval on **spotify/Backstage GitHub**. | Platform design team adjusts accordingly (as they see fit) and update the Figma DLS document. | Designed component is added to **spotify/Backstage GitHub** as an issue. | External or internal Backstage open source contributors build the component. | External or internal contributors add the component to the **Backstage Storybook**. 🎉 | +| Step 1 | Step 2 | Step 3 | Step 4 | Step 5 | Step 6 | +| :-------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- | +| Platform design team submits an issue to **backstage/backstage GitHub** with a potential component. | Backstage community offers feedback or approval on **backstage/backstage GitHub**. | Platform design team adjusts accordingly (as they see fit) and update the Figma DLS document. | Designed component is added to **backstage/backstage GitHub** as an issue. | External or internal Backstage open source contributors build the component. | External or internal contributors add the component to the **Backstage Storybook**. 🎉 | ### Building for Backstage @@ -56,9 +56,9 @@ referencing Figma documents to share specs and prototypes with the community. | :------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------- | | External or internal contributors use Backstage and come up with an idea of an entity to build for Backstage. | External or internal contributors refer to the Backstage Open Source design system documentation in the Figma DLS document. | External or internal contributors leverage the components and tokens from the Backstage Storybook. | External or internal contributors build their Backstage entity. | -| Step 5 | Step 6 | Step 7 | Step 8 | -| :------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | -| External or internal contributors make a pull request for their entity on spotify/Backstage GitHub for review. | Platform designers and devs review the entity and submit feedback or approval on spotify/Backstage GitHub. | External or internal contributors make the changes, pull request is approved and the entity is merged. It’s live on Backstage! 🎉 | If the entity happens to be or include a UX component, it’s added to Backstage Storybook as well. | +| Step 5 | Step 6 | Step 7 | Step 8 | +| :--------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | +| External or internal contributors make a pull request for their entity on backstage/backstage GitHub for review. | Platform designers and devs review the entity and submit feedback or approval on backstage/backstage GitHub. | External or internal contributors make the changes, pull request is approved and the entity is merged. It’s live on Backstage! 🎉 | If the entity happens to be or include a UX component, it’s added to Backstage Storybook as well. | The following diagram shows the relationship between the Backstage Design System and our foundation, which comprises of [Material UI](https://material-ui.com/) @@ -99,9 +99,10 @@ issues in GitHub with ‘design’ and/or ‘storybook’ - so feel free to brow tackle the tasks that interest you. If you have any questions regarding an issue, you can ask them in the comments section of the issue or on [Discord](https://discord.gg/EBHEGzX). We absolutely adore our external -contributors and will send you virtual semlas for your contributions! +contributors and will send you virtual +[semlas](https://en.wikipedia.org/wiki/Semla) for your contributions! -### Request a component. +### Request a component Create an issue (label it design and assign it to katz95) or send us a message on [Discord](https://discord.gg/EBHEGzX) (_#design_ channel) with details of @@ -135,5 +136,3 @@ contributing to Backstage as a designer is easy. From styling guidelines to UX principles to Figma documents, we’ll make sure you’re equipped to chip in on this project. We’re excited to work with you! In the meantime, we’d love to hear from you on [Discord](https://discord.gg/EBHEGzX). - -[Back to Docs](../README.md) diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md index dd19d4cd51..d10fb29e30 100644 --- a/docs/features/software-catalog/configuration.md +++ b/docs/features/software-catalog/configuration.md @@ -89,7 +89,7 @@ the catalog under the `catalog.locations` key, for example: catalog: locations: - type: url - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml ``` The locations added through static configuration can not be removed through the diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 3a1db235a0..9081009385 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -12,7 +12,7 @@ This both applies to objects given to and returned from the software catalog API, as well as to the descriptor files that the software catalog can ingest natively. In the API request/response cycle, a JSON representation is used, while the descriptor files are on YAML format to be more easily maintainable by -humans. However, the structure and semantics is the same in both cases. +humans. However, the structure and semantics are the same in both cases. Although it's possible to name catalog entity descriptor files however you wish, we recommend that you name them `catalog-info.yaml`. @@ -22,11 +22,15 @@ we recommend that you name them `catalog-info.yaml`. - [Overall Shape Of An Entity](#overall-shape-of-an-entity) - [Common to All Kinds: The Envelope](#common-to-all-kinds-the-envelope) - [Common to All Kinds: The Metadata](#common-to-all-kinds-the-metadata) +- [Common to All Kinds: Relations](#common-to-all-kinds-relations) - [Kind: Component](#kind-component) - [Kind: Template](#kind-template) - [Kind: API](#kind-api) - [Kind: Group](#kind-group) - [Kind: User](#kind-user) +- [Kind: Resource](#kind-resource) +- [Kind: System](#kind-system) +- [Kind: Domain](#kind-domain) ## Overall Shape Of An Entity @@ -113,7 +117,7 @@ data. Backstage specific entities have an `apiVersion` that is prefixed with `backstage.io/`, to distinguish them from other types of object that share the same type of structure. This may be relevant when co-hosting these -specifications with e.g. kubernetes object manifests, or when an organization +specifications with e.g. Kubernetes object manifests, or when an organization adds their own specific kinds of entity to the catalog. Early versions of the catalog will be using alpha/beta versions, e.g. @@ -256,8 +260,63 @@ component, like `java` or `go`. This field is optional, and currently has no special semantics. -Each tag must be sequences of `[a-zA-Z0-9]` separated by `-`, at most 63 -characters in total. +Each tag must be sequences of `[a-z0-9]` separated by `-`, at most 63 characters +in total. + +## Common to All Kinds: Relations + +The `relations` root field is a read-only list of relations, between the current +entity and other entities, described in the +[well-known relations section](well-known-relations.md). Relations are commonly +two-way, so that there's a pair of relation types each describing one direction +of the relation. + +A relation as part of a single entity that's read out of the API may look as +follows. + +```js +{ + // ... + "relations": [ + { + "target": { + "kind": "group", + "namespace": "default", + "name": "dev.infra" + }, + "type": "ownedBy" + } + ], + "spec": { + "owner": "dev.infra", + // ... + } +} +``` + +The fields of a relation are: + +| Field | Type | Description | +| ---------- | ------ | -------------------------------------------------------------------------------- | +| `target` | Object | A complete [compound reference](references.md) to the other end of the relation. | +| `type` | String | The type of relation FROM a source entity TO the target entity. | +| `metadata` | Object | Reserved for future use. | + +Entity descriptor YAML files are not supposed to contain this field. Instead, +catalog processors analyze the entity descriptor data and its surroundings, and +deduce relations that are then attached onto the entity as read from the +catalog. + +Where relations are produced, they are to be considered the authoritative source +for that piece of data. In the example above, a plugin would do better to +consume the relation rather than `spec.owner` for deducing the owner of the +entity, because it may even be the case that the owner isn't taken from the YAML +at all - it could be taken from a CODEOWNERS file nearby instead for example. +Also, the `spec.owner` is on a shortened form and may have semantics associated +with it (such as the default kind being `Group` if not specified). + +See the [well-known relations section](well-known-relations.md) for a list of +well-known / common relations and their semantics. ## Kind: Component @@ -418,7 +477,7 @@ of the `metadata.name` field. ### `metadata.tags` [optional] A list of strings that can be associated with the template, e.g. -`['Recommended', 'React']`. +`['recommended', 'react']`. This list will also be used in the frontend to display to the user so you can potentially search and group templates by these tags. @@ -740,3 +799,15 @@ with the default kind `Group` and the default namespace equal to the same namespace as the user. Only `Group` entities may be referenced. Most commonly, these entries point to groups in the same namespace, so in those cases it is sufficient to enter only the `metadata.name` field of those groups. + +## Kind: Resource + +This kind is not yet defined, but is reserved [for future use](system-model.md). + +## Kind: System + +This kind is not yet defined, but is reserved [for future use](system-model.md). + +## Kind: Domain + +This kind is not yet defined, but is reserved [for future use](system-model.md). diff --git a/docs/features/software-catalog/extending-the-model.md b/docs/features/software-catalog/extending-the-model.md index b045660202..cbacce40c7 100644 --- a/docs/features/software-catalog/extending-the-model.md +++ b/docs/features/software-catalog/extending-the-model.md @@ -4,6 +4,36 @@ title: Extending the model description: Documentation on Extending the model --- +The Backstage catalog [entity data model](descriptor-format.md) is based on the +[Kubernetes objects format](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/), +and borrows a lot of its semantics as well. This page describes those semantics +at a higher level and how to extend them to fit your organization. + +Backstage comes with a number of catalog concepts out of the box: + +- There are a number of builtin versioned _kinds_, such as `Component`, `User` + etc. These encapsulate the high level concept of an entity, and define the + schema for its entity definition data. +- An entity has both a _metadata_ object and a _spec_ object at the root. +- Each kind may or may not have a _type_. For example, there are several well + known types of component, such as `service` and `website`. These clarify the + more detailed nature of the entity, and may affect what features are exposed + in the interface. +- Entities may have a number of _[annotations](well-known-annotations.md)_ on + them. These can be added either by humans into the descriptor files, or added + by automated processes when the entity is ingested into the catalog. +- Entities may have a number of _labels_ on them. +- Entities may have a number of _relations_, expressing how they relate to each + other in different ways. + +We'll list different possibilities for extending this below. + +## Adding a New Kind + +> TODO: Fill in + +## Adding a New Type of an Existing Kind + Backstage natively supports tracking of the following component [`type`](descriptor-format.md)'s: @@ -20,13 +50,6 @@ track in Backstage, it is possible to add your own software types that fit your organization's data model. Inside Spotify our model has grown significantly over the years, and now includes ML models, Apps, data pipelines and many more. -## Adding a new type - -TODO: Describe what changes are needed to add a new type that shows up in the -catalog. - -## The Other type - It might be tempting to put software that doesn't fit into any of the existing types into Other. There are a few reasons why we advise against this; firstly, we have found that it is preferred to match the conceptual model that your @@ -36,6 +59,32 @@ through plugins. Different plugins are used for managing different types of components. For example, the -[Lighthouse plugin](https://github.com/spotify/backstage/tree/master/plugins/lighthouse) +[Lighthouse plugin](https://github.com/backstage/backstage/tree/master/plugins/lighthouse) only makes sense for Websites. The more specific you can be in how you model your software, the easier it is to provide plugins that are contextual. + +> TODO: Fill in + +## Changing the Validation Rules for Core Entity Fields + +> TODO: Fill in + +## Adding New Fields to the Metadata Object + +> TODO: Fill in + +## Adding New Fields to the Spec Object of an Existing Kind + +> TODO: Fill in + +## Adding a New Annotation + +> TODO: Fill in + +## Adding a New Label + +> TODO: Fill in + +## Adding a New Relation Type + +> TODO: Fill in diff --git a/docs/features/software-catalog/external-integrations.md b/docs/features/software-catalog/external-integrations.md index 00a9d95fc2..325bed5e4a 100644 --- a/docs/features/software-catalog/external-integrations.md +++ b/docs/features/software-catalog/external-integrations.md @@ -5,9 +5,159 @@ description: Documentation on External integrations to integrate systems with Backstage --- -Backstage natively supports storing software components in -[metadata YAML files](descriptor-format.md). However, companies that already -have an existing system for keeping track of software and its owners can -integrate such systems with Backstage. +Backstage natively supports importing catalog data through the use of +[entity descriptor YAML files](descriptor-format.md). However, companies that +already have an existing system for keeping track of software and its owners can +leverage those systems by integrating them with Backstage. This article shows +the most common way of doing that integration: by adding a custom catalog +_processor_. -TODO: Describe the API contract. +## Background + +The catalog has a frontend plugin part, that communicates via a service API to +the backend plugin part. The backend has a processing loop that repeatedly +ingests data from the sources you specify, to store them in its database. + +As a Backstage adopter, you would be able to customize or extend the catalog in +several ways - by replacing the entire backend API, or by replacing entire +implementation classes at certain points in the backend, or by leveraging the +ingestion process to fetch data from your own authoritative source. Each method +has benefits and drawbacks, but this article will focus on the last one of the +above. It is the one that is the most straight forward and future proof, and +leverages a lot of benefits that come with the builtin catalog. + +## Processors and the Ingestion Loop + +The catalog holds a number of registered locations, that were added either by +site admins or by individual Backstage users. Their purpose is to reference some +sort of data that the catalog shall keep itself up to date with. Each location +has a `type`, and a `target` that are both strings. + +```yaml +# Example location +type: url +target: https://github.com/backstage/backstage/blob/master/catalog-info.yaml +``` + +The builtin catalog backend has an ingestion loop that periodically goes through +all of these registered locations, and pushes them and their resulting output +through the list of _processors_. + +Processors are classes that the site admin has registered with the catalog at +startup. They are at the heart of all catalog logic, and have the ability to +read the contents of locations, modify in-flight entities that were read out of +a location, perform validation, and more. The catalog comes with a set of +builtin processors, that have the ability to read from a list of well known +location types, to perform the basic processing needs, etc, but more can be +added by the organization that adopts Backstage. + +We will now show the process of creating a new processor and location type, +which enables the ingestion of catalog data from an existing external API. + +## Deciding on the New Locations + +The first step is to decide how we want to point at the system that holds our +data. Let's assume that it is internally named System-X and can be reached +through HTTP REST calls to its API. + +Let's decide that our locations shall take the following form: + +```yaml +type: system-x +target: http://systemx.services.example.net/api/v2 +``` + +It got its own made-up `type`, and the `target` conveniently points to the +actual API endpoint to talk to. + +So now we have to make the catalog aware of such a location so that it can start +feeding it into the ingestion loop. For this kind of an integration, you'd +typically want to add it to the list of statically always-available locations in +the config. + +```yaml +# In app-config.yaml +catalog: + locations: + - type: system-x + target: http://systemx.services.example.net/api/v2 +``` + +If you start up the backend now, it will start to periodically say that it could +not find a processor that supports that location. So let's make a processor that +does so! + +## Creating a Catalog Data Reader Processor + +The recommended way of instantiating the catalog backend classes is to use the +[`CatalogBuilder`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/service/CatalogBuilder.ts), +as illustrated in the +[example backend here](https://github.com/backstage/backstage/blob/master/packages/backend/src/plugins/catalog.ts). +We will create a new +[`CatalogProcessor`](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/src/ingestion/types.ts) +subclass that can be added to this catalog builder. + +It is up to you where you put the code for this new processor class. For quick +experimentation you could place it in your backend package, but we recommend +putting all extensions like this in a backend plugin package of their own in the +`plugins` folder of your Backstage repo. + +The class will have this basic structure: + +```ts +import { UrlReader } from '@backstage/backend-common'; +import { LocationSpec } from '@backstage/catalog-model'; +import { + results, + CatalogProcessor, + CatalogProcessorEmit, +} from '@backstage/plugin-catalog-backend'; + +// A processor that reads from the fictional System-X +export class SystemXReaderProcessor implements CatalogProcessor { + constructor(private readonly reader: UrlReader) {} + + async readLocation( + location: LocationSpec, + _optional: boolean, + emit: CatalogProcessorEmit, + ): Promise { + // Pick a custom location type string. A location will be + // registered later with this type. + if (location.type !== 'system-x') { + return false; + } + + try { + // Use the builtin reader facility to grab data from the + // API. If you prefer, you can just use plain fetch here + // (from the cross-fetch package), or any other method of + // your choosing. + const data = await this.reader.read(location.target); + const json = JSON.parse(data.toString()); + // Repeatedly call emit(results.entity(location, )) + } catch (error) { + const message = `Unable to read ${location.type}, ${error}`; + emit(results.generalError(location, message)); + } + + return true; + } +} +``` + +The key points to note are: + +- Make a class that implements `CatalogProcessor` +- Only act on location types that you care about, and leave the rest alone by + returning `false` +- Read the data from the external system in any way you see fit. Use the + location `target` field if you designed it as mentioned above +- Call `emit` any number of times with the results of that process +- Finally return `true` + +You should now be able to instantiate this class in your backend, and add it to +the `CatalogBuilder` using the `addProcessors` method. + +Start up the backend - it should now start reading from the previously +registered location and you'll see your entities start to appear in Backstage. diff --git a/docs/features/software-catalog/index.md b/docs/features/software-catalog/index.md index 4ba83146db..08e6260e80 100644 --- a/docs/features/software-catalog/index.md +++ b/docs/features/software-catalog/index.md @@ -19,7 +19,7 @@ are then harvested and visualized in Backstage. ## How it works -Backstage and the Backstage Service Catalog makes it easy for one team to manage +Backstage and the Backstage Service Catalog make it easy for one team to manage 10 services — and makes it possible for your company to manage thousands of them. @@ -33,10 +33,10 @@ More specifically, the Service Catalog enables two main use-cases: ## Getting Started -The Software Catalog is available to browse on the start page at `/`. If you've -followed [Installing in your Backstage App](./installation.md) in your separate -App or [Getting Started with Backstage](../../getting-started) for this repo, -you should be able to browse the catalog at `http://localhost:3000`. +The Software Catalog is available to browse at `/catalog`. If you've followed +[Installing in your Backstage App](./installation.md) in your separate App or +[Getting Started with Backstage](../../getting-started) for this repo, you +should be able to browse the catalog at `http://localhost:3000`. ![](../../assets/software-catalog/service-catalog-home.png) @@ -62,11 +62,11 @@ Users can register new components by going to `/create` and clicking the Backstage expects the full URL to the YAML in your source control. Example: ```bash -https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml +https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml ``` _More examples can be found -[here](https://github.com/spotify/backstage/tree/master/packages/catalog-model/examples)._ +[here](https://github.com/backstage/backstage/tree/master/packages/catalog-model/examples)._ ![](../../assets/software-catalog/bsc-register-2.png) @@ -91,7 +91,7 @@ above example can be added using the following configuration: catalog: locations: - type: url - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/components/artist-lookup-component.yaml ``` More information about catalog configuration can be found @@ -135,7 +135,7 @@ in the catalog. ![tools](https://backstage.io/blog/assets/20-05-20/tabs.png) The Backstage platform can be customized by incorporating -[existing open source plugins](https://github.com/spotify/backstage/tree/master/plugins), +[existing open source plugins](https://github.com/backstage/backstage/tree/master/plugins), or by [building your own](../../plugins/index.md). ## Links diff --git a/docs/features/software-catalog/installation.md b/docs/features/software-catalog/installation.md index 26990033aa..b2afd62878 100644 --- a/docs/features/software-catalog/installation.md +++ b/docs/features/software-catalog/installation.md @@ -56,7 +56,7 @@ The catalog components depend on a number of other [Utility APIs](../../api/utility-apis.md) to function, including at least the `ErrorApi` and `StorageApi`. You can find an example of how to install these in your app -[here](https://github.com/spotify/backstage/blob/61c3a7e5b750dc7c059ef16b188594d31b2c04c2/packages/app/src/apis.ts#L80). +[here](https://github.com/backstage/backstage/blob/61c3a7e5b750dc7c059ef16b188594d31b2c04c2/packages/app/src/apis.ts#L80). ## Gotchas that we will fix @@ -122,6 +122,7 @@ export default async function createPlugin({ entitiesCatalog, locationsCatalog, locationReader, + db, logger, ); @@ -167,21 +168,21 @@ catalog: locations: # Backstage Example Component - type: url - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml - type: url - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/playback-order-component.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/playback-order-component.yaml - type: url - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/podcast-api-component.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/podcast-api-component.yaml - type: url - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/queue-proxy-component.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/queue-proxy-component.yaml - type: url - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/searcher-component.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/searcher-component.yaml - type: url - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/playback-lib-component.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/playback-lib-component.yaml - type: url - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/www-artist-component.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/www-artist-component.yaml - type: url - target: https://github.com/spotify/backstage/blob/master/packages/catalog-model/examples/shuffle-api-component.yaml + target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/shuffle-api-component.yaml ``` ### Running the Backend diff --git a/docs/features/software-catalog/system-model.md b/docs/features/software-catalog/system-model.md index 44dac13d65..53f49d5df9 100644 --- a/docs/features/software-catalog/system-model.md +++ b/docs/features/software-catalog/system-model.md @@ -8,7 +8,7 @@ We believe that a strong shared understanding and terminology around software and resources leads to a better Backstage experience. _This description originates from -[this RFC](https://github.com/spotify/backstage/issues/390). Note that some of +[this RFC](https://github.com/backstage/backstage/issues/390). Note that some of the concepts are not yet supported in Backstage._ ## Core Entities @@ -113,5 +113,5 @@ Backstage currently supports Components and APIs. ## Links -- [Original RFC](https://github.com/spotify/backstage/issues/390) +- [Original RFC](https://github.com/backstage/backstage/issues/390) - [YAML file format](../../architecture-decisions/adr002-default-catalog-file-format.md) diff --git a/docs/features/software-catalog/well-known-annotations.md b/docs/features/software-catalog/well-known-annotations.md index 40a4ca3ea1..1f5e851064 100644 --- a/docs/features/software-catalog/well-known-annotations.md +++ b/docs/features/software-catalog/well-known-annotations.md @@ -2,9 +2,9 @@ id: well-known-annotations title: Well-known Annotations on Catalog Entities sidebar_label: Well-known Annotations -description: Documentation on lists a number of well known Annotations, that +description: Documentation that lists a number of well known Annotations, that have defined semantics. They can be attached to catalog entities and consumed -by plugins as needed +by plugins as needed. --- This section lists a number of well known @@ -23,7 +23,7 @@ use. # Example: metadata: annotations: - backstage.io/managed-by-location: github:http://github.com/spotify/backstage/catalog-info.yaml + backstage.io/managed-by-location: github:http://github.com/backstage/backstage/catalog-info.yaml ``` The value of this annotation is a so called location reference string, that @@ -47,7 +47,7 @@ colon is always present. # Example: metadata: annotations: - backstage.io/techdocs-ref: github:https://github.com/spotify/backstage.git + backstage.io/techdocs-ref: github:https://github.com/backstage/backstage.git ``` The value of this annotation is a location reference string (see above). If this @@ -75,7 +75,7 @@ that entity. # Example: metadata: annotations: - github.com/project-slug: spotify/backstage + github.com/project-slug: backstage/backstage ``` The value of this annotation is the so-called slug that identifies a project on @@ -93,7 +93,7 @@ that entity. # Example: metadata: annotations: - github.com/team-slug: spotify/backstage-core + github.com/team-slug: backstage/maintainers ``` The value of this annotation is the so-called slug that identifies a team on @@ -146,7 +146,7 @@ that entity. # Example: metadata: annotations: - rollbar.com/project-slug: spotify/pump-station + rollbar.com/project-slug: backstage/pump-station ``` The value of this annotation is the so-called slug (or alternatively, the ID) of @@ -158,6 +158,27 @@ fallback (`rollbar.organization` followed by `organization.name`). Specifying this annotation may enable Rollbar related features in Backstage for that entity. +### circleci.com/project-slug + +```yaml +# Example: +metadata: + annotations: + circleci.com/project-slug: github/spotify/pump-station +``` + +The value of this annotation is the so-called slug (or alternatively, the ID) of +a [CircleCI](https://circleci.com/) project within your organization. The value +can be the format of `[source-control-manager]/[organization]/[project-slug]` or +just `[organization]/[project-slug]`. When the `[source-control-manager]` slug +is omitted, `bitbucket` will be used as a fallback. + +Specifying this annotation will cause the CI/CD features in Backstage to display +data from CircleCI for that entity. + +Providing both the `github.com/project-slug` and `circleci.com/project-slug` +annotations can cause problems as both may be used for CI/CD features. + ### backstage.io/ldap-rdn, backstage.io/ldap-uuid, backstage.io/ldap-dn ```yaml @@ -173,6 +194,22 @@ The value of these annotations are the corresponding attributes that were found when ingestion the entity from LDAP. Not all of them may be present, depending on what attributes that the server presented at ingestion time. +### sonarqube.org/project-key + +```yaml +# Example: +metadata: + annotations: + sonarqube.org/project-key: pump-station +``` + +The value of this annotation is the project key of a +[SonarQube](https://sonarqube.org) or [SonarCloud](https://sonarcloud.io) +project within your organization. + +Specifying this annotation may enable SonarQube related features in Backstage +for that entity. + ## Deprecated Annotations The following annotations are deprecated, and only listed here to aid in diff --git a/docs/features/software-catalog/well-known-relations.md b/docs/features/software-catalog/well-known-relations.md new file mode 100644 index 0000000000..fe1c32b02f --- /dev/null +++ b/docs/features/software-catalog/well-known-relations.md @@ -0,0 +1,83 @@ +--- +id: well-known-relations +title: Well-known Relations between Catalog Entities +sidebar_label: Well-known Relations +description: Documentation that lists a number of well known Relations, that +have defined semantics. They can be attached to catalog entities and consumed +by plugins as needed. +--- + +This section lists a number of well known +[entity relation types](descriptor-format.md#common-to-all-kinds-relations), +that have defined semantics. They can be attached to catalog entities and +consumed by plugins as needed. + +If you are looking to extend the set of relations, see +[Extending the model](extending-the-model.md). + +## Relations + +This is a (non-exhaustive) list of relations that are known to be in active use. + +Each relation has a _source_ (implicitly: the entity that holds the relation), a +_target_ (the entity to which the source has a relation), and a _type_ that +tells what relation the source has with the target. The relation is directional; +there are commonly pairs of relation types and the entity at the other end will +have the opposite relation in the opposite direction (e.g. when querying for +`A`, you will see `A.ownedBy.B`, and when querying `B`, you will see +`B.ownerOf.A`). + +### `ownedBy` and `ownerOf` + +An ownership relation where the owner is usually an organizational entity +([User](descriptor-format.md#kind-user) or +[Group](descriptor-format.md#kind-group)), and the other entity can be anything. + +In Backstage, the owner of an entity is the singular entity (commonly a team) +that bears ultimate responsibility for the entity, and has the authority and +capability to develop and maintain it. They will be the point of contact if +something goes wrong, or if features are to be requested. The main purpose of +this relation is for display purposes in Backstage, so that people looking at +catalog entities can get an understanding of to whom this entity belongs. It is +not to be used by automated processes to for example assign authorization in +runtime systems. There may be others that also develop or otherwise touch the +entity, but there will always be one ultimate owner. + +This relation is commonly generated based on `spec.owner` of the owned entity, +where present. + +### `consumesApi` and `providesApi` + +A relation with an [API](descriptor-format.md#kind-api) entity, typically from a +[Component](descriptor-format.md#kind-component) or +[System](descriptor-format.md#kind-system). + +These relations express that a component or system either exposes an API - +meaning that it hosts callable endpoints from which you can consume that API - +or that they are dependent on being able to consume that API. + +This relation is commonly generated based on `spec.implementsApis` of the +component or system in question. + +### `dependsOn` and `dependencyOf` + +A relation denoting a dependency on another entity. + +This relation is a general expression of being in need of that other entity for +an entity to function. It can for example be used to express that a website +component needs a library component as part of its build, or that a service +component uses a persistent storage resource. + +### `parentOf` and `childOf` + +A parent/child relation to build up a tree, used for example to describe the +organizational structure between [Groups](descriptor-format.md#kind-group). + +This relation is commonly based on `spec.parent` and/or `spec.children`. + +### `memberOf` and `hasMember` + +A membership relation, typically for [Users](descriptor-format.md#kind-user) in +[Groups](descriptor-format.md#kind-group). + +This relation is commonly based on `spec.memberOf`. diff --git a/docs/features/software-templates/adding-templates.md b/docs/features/software-templates/adding-templates.md index 5a4e0049ab..75a75003f7 100644 --- a/docs/features/software-templates/adding-templates.md +++ b/docs/features/software-templates/adding-templates.md @@ -5,8 +5,8 @@ description: Documentation on Adding your own Templates --- Templates are stored in the **Service Catalog** under a kind `Template`. The -minimum that the template skeleton needs is a `template.yaml` but it would be -good to also have some files in there that can be templated in. +minimum that is needed to define a template is a `template.yaml` file, but it +would be good to also have some files in there that can be templated in. A simple `template.yaml` definition might look something like this: @@ -61,7 +61,7 @@ support to load the location will also need to be added to the Catalog. You can add the template files to the catalog through [static location configuration](../software-catalog/configuration.md#static-location-configuration), -for example +for example: ```yaml catalog: @@ -100,11 +100,11 @@ curl \ --location \ --request POST 'localhost:7000/api/catalog/locations' \ --header 'Content-Type: application/json' \ - --data-raw "{\"type\": \"github\", \"target\": \"https://${YOUR GITHUB REPO}blob/master/${PATH TO FOLDER}/template.yaml\"}" + --data-raw "{\"type\": \"github\", \"target\": \"https://${GITHUB URL}/${YOUR GITHUB ORG/REPO}/blob/master/${PATH TO FOLDER}/template.yaml\"}" ``` -This should then have added the catalog, and also should now be listed under the -create page at http://localhost:3000/create. +This should then have been added the catalog, and be listed under the create +page at http://localhost:3000/create. The `type` field which is chosen in the request to add the `template.yaml` to the Service Catalog here, will become the `PreparerKey` which will be used to diff --git a/docs/features/software-templates/extending/create-your-own-preparer.md b/docs/features/software-templates/extending/create-your-own-preparer.md index 80287c6ce1..5419748c3a 100644 --- a/docs/features/software-templates/extending/create-your-own-preparer.md +++ b/docs/features/software-templates/extending/create-your-own-preparer.md @@ -15,10 +15,10 @@ location protocols: - `github://` These two are added to the `PreparersBuilder` and then passed into the -`createRouter` function of the `@spotify/plugin-scaffolder-backend` +`createRouter` function of the `@backstage/plugin-scaffolder-backend`. -A full example backend can be found -[here](https://github.com/spotify/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts), +A full example backend can be found in +[`scaffolder.ts`](https://github.com/backstage/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts), but it looks something like the following ```ts @@ -56,7 +56,7 @@ when added to the service catalog. You can see more about this `PreparerKey` here in [Register your own template](../adding-templates.md) **note:** Currently the catalog supports loading definitions from GitHub + Local -Files, which translate into the two `PreparerKeys` `file` and `github`. To load +Files, which translate into the two `PreparerKeys`: `file` and `github`. To load from other places, not only will there need to be another preparer, but the support to load the location will also need to be added to the Catalog. @@ -85,8 +85,8 @@ and put the contents into a temporary directory and return that directory path. Some good examples exist here: -- https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/stages/prepare/file.ts -- https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/stages/prepare/github.ts +- https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/stages/prepare/file.ts +- https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/stages/prepare/github.ts ### Registering your own Preparer diff --git a/docs/features/software-templates/extending/create-your-own-publisher.md b/docs/features/software-templates/extending/create-your-own-publisher.md index 546980f033..97854c999a 100644 --- a/docs/features/software-templates/extending/create-your-own-publisher.md +++ b/docs/features/software-templates/extending/create-your-own-publisher.md @@ -18,11 +18,11 @@ Currently we provide the following `publishers`: - `github` This publisher is passed through to the `createRouter` function of the -`@spotify/plugin-scaffolder-backend`. Currently, only one publisher is +`@backstage/plugin-scaffolder-backend`. Currently, only one publisher is supported, but PR's are always welcome. An full example backend can be found -[here](https://github.com/spotify/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts), +[here](https://github.com/backstage/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts), but it looks something like the following ```ts @@ -82,7 +82,7 @@ Now it's up to you to implement the `publish` function and return Some good examples exist here: -- https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/stages/publish/github.ts +- https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/stages/publish/github.ts ### Registering your own Publisher diff --git a/docs/features/software-templates/extending/create-your-own-templater.md b/docs/features/software-templates/extending/create-your-own-templater.md index d4a6eef5d2..63acd38286 100644 --- a/docs/features/software-templates/extending/create-your-own-templater.md +++ b/docs/features/software-templates/extending/create-your-own-templater.md @@ -17,10 +17,10 @@ Currently we provide the following templaters: - `cookiecutter` This templater is added to the `TemplaterBuilder` and then passed into the -`createRouter` function of the `@spotify/plugin-scaffolder-backend` +`createRouter` function of the `@backstage/plugin-scaffolder-backend` An full example backend can be found -[here](https://github.com/spotify/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts), +[here](https://github.com/backstage/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts), but it looks something like the following ```ts @@ -96,7 +96,7 @@ Now it's up to you to implement the `run` function, and then return a Some good examples exist here: -- https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/stages/templater/cookiecutter.ts +- https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/stages/templater/cookiecutter.ts ### Registering your own Templater diff --git a/docs/features/software-templates/extending/index.md b/docs/features/software-templates/extending/index.md index 944bf0e3ca..aaf42d6b12 100644 --- a/docs/features/software-templates/extending/index.md +++ b/docs/features/software-templates/extending/index.md @@ -51,7 +51,7 @@ passed through to the scaffolder backend. ### How it works Most of the heavy lifting is done in the -[router.ts](https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/src/service/router.ts#L93) +[router.ts](https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/src/service/router.ts#L93) file in the `scaffolder-backend` plugin. There are two routes defined in the router: `POST /v1/jobs` and diff --git a/docs/features/software-templates/index.md b/docs/features/software-templates/index.md index ae121f8029..3ebb426466 100644 --- a/docs/features/software-templates/index.md +++ b/docs/features/software-templates/index.md @@ -39,17 +39,17 @@ internally. ![Enter some variables](../../assets/software-templates/template-picked.png) After filling in these variables, you'll get some more fields to fill out which -are required for backstage usage: the owner, (which is a `user` in the backstage +are required for backstage usage: the owner (which is a `user` in the backstage system), the `storePath` (which right now must be a GitHub Organisation or -GitHub user), a non-existing github repository name in the format -`organisation/reponame`, and a GitHub team or user account which should be +GitHub user and a non-existing GitHub repository name in the format +`organisation/reponame`), and a GitHub team or user account which should be granted admin access to the repository. ![Enter backstage vars](../../assets/software-templates/template-picked-2.png) ### Run! -Once you've entered values and confirmed, you'll then get a modal with live +Once you've entered values and confirmed, you'll then get a popup box with live progress of what is currently happening with the creation of your template. ![Templating Running](../../assets/software-templates/running.png) @@ -70,6 +70,6 @@ you to the registered component in the catalog: ![Catalog](../../assets/software-templates/go-to-catalog.png) -And then you'll also be able to see it in the Catalog View table +And then you'll also be able to see it in the Catalog View table: ![Catalog](../../assets/software-templates/added-to-the-catalog-list.png) diff --git a/docs/features/software-templates/installation.md b/docs/features/software-templates/installation.md index 838c5e2d11..724b86aed1 100644 --- a/docs/features/software-templates/installation.md +++ b/docs/features/software-templates/installation.md @@ -111,44 +111,8 @@ export default async function createPlugin({ templaters.register('cookiecutter', cookiecutterTemplater); templaters.register('cra', craTemplater); - const filePreparer = new FilePreparer(); - const githubPreparer = new GithubPreparer(); - const gitlabPreparer = new GitlabPreparer(config); - const preparers = new Preparers(); - - preparers.register('file', filePreparer); - preparers.register('github', githubPreparer); - preparers.register('gitlab', gitlabPreparer); - preparers.register('gitlab/api', gitlabPreparer); - - const publishers = new Publishers(); - - const githubToken = config.getString('scaffolder.github.token'); - const repoVisibility = config.getString( - 'scaffolder.github.visibility', - ) as RepoVisibilityOptions; - - const githubClient = new Octokit({ auth: githubToken }); - const githubPublisher = new GithubPublisher({ - client: githubClient, - token: githubToken, - repoVisibility, - }); - publishers.register('file', githubPublisher); - publishers.register('github', githubPublisher); - - const gitLabConfig = config.getOptionalConfig('scaffolder.gitlab.api'); - - if (gitLabConfig) { - const gitLabToken = gitLabConfig.getString('token'); - const gitLabClient = new Gitlab({ - host: gitLabConfig.getOptionalString('baseUrl'), - token: gitLabToken, - }); - const gitLabPublisher = new GitlabPublisher(gitLabClient, gitLabToken); - publishers.register('gitlab', gitLabPublisher); - publishers.register('gitlab/api', gitLabPublisher); - } + const preparers = await Preparers.fromConfig(config, { logger }); + const publishers = await Publishers.fromConfig(config, { logger }); const dockerClient = new Docker(); return await createRouter({ @@ -192,11 +156,11 @@ catalog: locations: # Backstage Example Templates - type: url - target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/react-ssr-template/template.yaml + target: https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/sample-templates/react-ssr-template/template.yaml - type: url - target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/springboot-grpc-template/template.yaml + target: https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/sample-templates/springboot-grpc-template/template.yaml - type: url - target: https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/sample-templates/create-react-app/template.yaml + target: https://github.com/backstage/backstage/blob/master/plugins/scaffolder-backend/sample-templates/create-react-app/template.yaml - type: url target: https://github.com/spotify/cookiecutter-golang/blob/master/template.yaml ``` @@ -211,22 +175,16 @@ docs on creating private GitHub access tokens is available Note that the need for private GitHub access tokens will be replaced with GitHub Apps integration further down the line. -#### Github +#### GitHub -The Github access token is retrieved from environment variables via the config. +The GitHub access token is retrieved from environment variables via the config. The config file needs to specify what environment variable the token is retrieved from. Your config should have the following objects. You can configure who can see the new repositories that the scaffolder creates by specifying `visibility` option. Valid options are `public`, `private` and -`internal`. `internal` options is for GitHub Enterprise clients, which means -public within the organization. - -#### Gitlab - -For Gitlab, we currently support the configuration of the GitLab publisher and -allows to configure the private access token and the base URL of a GitLab -instance: +`internal`. The `internal` option is for GitHub Enterprise clients, which means +public within the enterprise. ```yaml scaffolder: @@ -234,6 +192,16 @@ scaffolder: token: $env: GITHUB_TOKEN visibility: public # or 'internal' or 'private' +``` + +#### GitLab + +For GitLab, we currently support the configuration of the GitLab publisher and +allows to configure the private access token and the base URL of a GitLab +instance: + +```yaml +scaffolder: gitlab: api: baseUrl: https://gitlab.com diff --git a/docs/features/techdocs/FAQ.md b/docs/features/techdocs/FAQ.md index e81e9d82c7..de424778cb 100644 --- a/docs/features/techdocs/FAQ.md +++ b/docs/features/techdocs/FAQ.md @@ -17,14 +17,12 @@ This page answers frequently asked questions about [TechDocs](README.md). TechDocs is using [MkDocs](https://www.mkdocs.org/) to build project documentation under the hood. Documentation built with the -[techdocs-container](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/README.md) -is using the MkDocs -[Material Theme](https://github.com/squidfunk/mkdocs-material). +[techdocs-container](https://github.com/backstage/techdocs-container) is using +the MkDocs [Material Theme](https://github.com/squidfunk/mkdocs-material). #### What is the mkdocs-techdocs-core plugin? -The -[mkdocs-techdocs-core](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/techdocs-core/README.md) +The [mkdocs-techdocs-core](https://github.com/backstage/mkdocs-techdocs-core) package is a MkDocs Plugin that works like a wrapper around multiple MkDocs plugins (e.g. [MkDocs Monorepo Plugin](https://github.com/spotify/mkdocs-monorepo-plugin)) as diff --git a/docs/features/techdocs/README.md b/docs/features/techdocs/README.md index cec5b63cc7..f1cf637997 100644 --- a/docs/features/techdocs/README.md +++ b/docs/features/techdocs/README.md @@ -40,10 +40,10 @@ about TechDocs and the philosophy in its | [TechDocs V.2 🔮⌛][v2] | Easy adoption of TechDocs (whatever environment you have) [See V.2 Use Cases.](#techdocs-v2) | | [TechDocs V.3 🔮⌛][v3] | Build a widget (plugin) framework so that contributors can easily contribute features to TechDocs - that others can use. [See V.3 Use Cases.](#techdocs-v3) | -[v0]: https://github.com/spotify/backstage/milestone/15 -[v1]: https://github.com/spotify/backstage/milestone/16 -[v2]: https://github.com/spotify/backstage/milestone/22 -[v3]: https://github.com/spotify/backstage/milestone/17 +[v0]: https://github.com/backstage/backstage/milestone/15 +[v1]: https://github.com/backstage/backstage/milestone/16 +[v2]: https://github.com/backstage/backstage/milestone/22 +[v3]: https://github.com/backstage/backstage/milestone/17 @@ -82,7 +82,9 @@ for companies to adopt. This involves (something like) the following work items. - “Solidify” work and “Mkdocs stabilization” work that has come out of our Q3 end-to-end work. - Improve/simplify the get up and running process. -- Introduce doc template Software Templates. +- Introduce new documentation templates. +- Extend the already existing docs-template to have options of different + documentation types. - Enable companies to choose their own storage (S3 for example). - Enable companies to choose their own source code hosting provider (GitHub, GitLab, and so). @@ -107,18 +109,16 @@ migrate Spotify's existing TechDocs features to open source. | ------------------------------------------- | -------------------------------------------------------- | | Frontend | [`@backstage/plugin-techdocs`][techdocs/frontend] | | Backend | [`@backstage/plugin-techdocs-backend`][techdocs/backend] | -| Docker Container (for generating doc sites) | [`packages/techdocs-container`][techdocs/container] | -| CLI (for local development) | [`packages/techdocs-cli`][techdocs/cli] | +| Docker Container (for generating doc sites) | [`techdocs-container`][techdocs/container] | +| CLI (for local development) | [`@techdocs/cli`][techdocs/cli] | [getting started]: getting-started.md [concepts]: concepts.md [creating and publishing documentation]: creating-and-publishing.md [faq]: FAQ.md 'Frequently asked questions' [techdocs/frontend]: - https://github.com/spotify/backstage/blob/master/plugins/techdocs + https://github.com/backstage/backstage/blob/master/plugins/techdocs [techdocs/backend]: - https://github.com/spotify/backstage/blob/master/plugins/techdocs-backend -[techdocs/container]: - https://github.com/spotify/backstage/blob/master/packages/techdocs-container -[techdocs/cli]: - https://github.com/spotify/backstage/blob/master/packages/techdocs-cli + https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend +[techdocs/container]: https://github.com/backstage/techdocs-container +[techdocs/cli]: https://github.com/backstage/techdocs-cli diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md index 13144f8df0..1675c64288 100644 --- a/docs/features/techdocs/concepts.md +++ b/docs/features/techdocs/concepts.md @@ -14,7 +14,7 @@ The TechDocs Core Plugin is an [MkDocs](https://www.mkdocs.org/) plugin created as a wrapper around multiple MkDocs plugins and Python Markdown extensions to standardize the configuration of MkDocs used for TechDocs. -[TechDocs Core](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/techdocs-core/README.md) +[TechDocs Core](https://github.com/backstage/mkdocs-techdocs-core) ### TechDocs container @@ -23,14 +23,14 @@ The TechDocs container is a Docker container available at pages, including stylesheets and scripts from Python flavored Markdown, through MkDocs. -[TechDocs Container](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/README.md) +[TechDocs Container](https://github.com/backstage/techdocs-container) ### TechDocs publisher The `techdocs-backend` plugin currently comes with one publisher - `LocalPublish`. -[TechDocs Backend](https://github.com/spotify/backstage/tree/master/plugins/techdocs-backend) +[TechDocs Backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend) More standalone publishers will come in the near future... @@ -41,7 +41,7 @@ documentation for publishing. Currently it mostly acts as a wrapper around the TechDocs container and provides an easy-to-use interface for our docker container. -[TechDocs CLI](https://github.com/spotify/backstage/blob/master/packages/techdocs-cli/README.md) +[TechDocs CLI](https://github.com/backstage/techdocs-cli) ### TechDocs Reader @@ -53,7 +53,7 @@ The TechDocs Reader purpose is also to open up the opportunity to integrate TechDocs widgets for a customized full-featured TechDocs experience. ([coming soon V.3](./README.md#project-roadmap)) -[TechDocs Reader](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/README.md) +[TechDocs Reader](https://github.com/backstage/backstage/blob/master/plugins/techdocs/src/reader/README.md) ### Transformers @@ -62,4 +62,4 @@ Reader. The reason why transformers were introduced was to provide a way to transform the HTML content on pre and post render (e.g. rewrite docs links or modify css). -[Transformers API docs](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/README.md) +[Transformers API docs](https://github.com/backstage/backstage/blob/master/plugins/techdocs/src/reader/README.md) diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index 947e6de371..38f452dcf3 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -30,7 +30,9 @@ scratch. Your working Backstage instance should by default have a documentation template added. If not, follow these [instructions](../software-templates/installation.md#adding-templates) to add -the documentation template. +the documentation template. The template creates a component with only TechDocs +configuration and default markdown files as below mentioned in manual +documentation setup, and is otherwise empty. ![Documentation Template](../../assets/techdocs/documentation-template.png) diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 72efb6eee0..cbbbc1e6cd 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -73,10 +73,10 @@ required. ### Disable Docker in Docker situation (Optional) -The TechDocs backend plugin runs a docker container with mkdocs to generate the -frontend of the docs from source files (Markdown). If you are deploying -Backstage using Docker, this will mean that your Backstage Docker container will -try to run another Docker container for TechDocs backend. +The TechDocs backend plugin runs a docker container with mkdocs installed to +generate the frontend of the docs from source files (Markdown). If you are +deploying Backstage using Docker, this will mean that your Backstage Docker +container will try to run another Docker container for TechDocs backend. To avoid this problem, we have a configuration available. You can set a value in your `app-config.yaml` that tells the techdocs generator if it should run the @@ -90,10 +90,23 @@ techdocs: ``` Setting `generators.techdocs` to `local` means you will have to make sure your -environment is compatible with techdocs. You will have to install the -`mkdocs-techdocs-container` and 'mkdocs' package from pip, as well as graphviz -and plantuml from your package manager. This has only been tested with python -3.7 and python 3.8. +environment is compatible with techdocs. + +You will have to install the `mkdocs` and `mkdocs-techdocs-core` package from +pip, as well as `graphviz` and `plantuml` from your OS package manager (e.g. +apt). See our +[Dockerfile](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/Dockerfile) +for the latest requirements. You should be trying to match your Dockerfile with +this one. + +Note: We recommend Python version 3.7 or higher. + +Caveat: Please install the `mkdocs-techdocs-core` package after all other Python +packages. The order is important to make sure we get correct version of some of +the dependencies. For example, we want `Markdown` version to be +[3.2.2](https://github.com/spotify/backstage/blob/f9f70c225548017b6a14daea75b00fbd399c11eb/packages/techdocs-container/techdocs-core/requirements.txt#L11). +You can also explicitly install `Markdown==3.2.2` after installing all other +Python packages. ## Run Backstage locally diff --git a/docs/getting-started/app-custom-theme.md b/docs/getting-started/app-custom-theme.md index 97876c2ba1..79cd405198 100644 --- a/docs/getting-started/app-custom-theme.md +++ b/docs/getting-started/app-custom-theme.md @@ -37,7 +37,7 @@ in combination with [createMuiTheme](https://material-ui.com/customization/theming/#createmuitheme-options-args-theme) from [@material-ui/core](https://www.npmjs.com/package/@material-ui/core). See the -[@backstage/theme source](https://github.com/spotify/backstage/tree/master/packages/theme/src) +[@backstage/theme source](https://github.com/backstage/backstage/tree/master/packages/theme/src) and the implementation of the `createTheme` function for how this is done. You can also create a theme from scratch that matches the `BackstageTheme` type diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md index 670c7fbf98..c35eded6a5 100644 --- a/docs/getting-started/create-an-app.md +++ b/docs/getting-started/create-an-app.md @@ -13,7 +13,7 @@ need to run Backstage in your own environment. ## Create an app To create a Backstage app, you will need to have -[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed +[Node.js](https://nodejs.org/en/download/) Active LTS Release installed (currently v12). Backstage provides a utility for creating new apps. It guides you through the diff --git a/docs/getting-started/deployment-helm.md b/docs/getting-started/deployment-helm.md index e674d28742..e1f3ea7629 100644 --- a/docs/getting-started/deployment-helm.md +++ b/docs/getting-started/deployment-helm.md @@ -8,10 +8,10 @@ sidebar_label: Kubernetes and Helm # Helm charts An example Backstage app can be deployed in Kubernetes using the -[Backstage Helm charts](https://github.com/spotify/backstage/tree/master/contrib/chart/backstage) +[Backstage Helm charts](https://github.com/backstage/backstage/tree/master/contrib/chart/backstage). -First, choose a DNS name where backstage will be hosted create a yaml file for -your custom configuration. +First, choose a DNS name where Backstage will be hosted, and create a YAML file +for your custom configuration. ```yaml appConfig: @@ -31,8 +31,8 @@ appConfig: Then use it to run: -``` -git clone https://github.com/spotify/backstage.git +```bash +git clone https://github.com/backstage/backstage.git cd contrib/chart/backstage helm dependency update helm install -f backstage-mydomain.yaml backstage . @@ -61,4 +61,4 @@ backstage-ingress * 123.1.2.3 80 17m > **NOTE**: this is not a production ready deployment. For more information on how to customize the deployment check the -[README](https://github.com/spotify/backstage/tree/master/contrib/chart/backstage/README.md). +[README](https://github.com/backstage/backstage/tree/master/contrib/chart/backstage/README.md). diff --git a/docs/getting-started/deployment-k8s.md b/docs/getting-started/deployment-k8s.md index 69aa59a600..bc24894ed1 100644 --- a/docs/getting-started/deployment-k8s.md +++ b/docs/getting-started/deployment-k8s.md @@ -4,10 +4,10 @@ title: Kubernetes description: Documentation on Kubernetes and K8s Deployment --- -Backstage itself provides tooling up to the point of building docker images. +Backstage itself provides tooling up to the point of building Docker images. Beyond that point we do not have an opinionated way to deploy Backstage within Kubernetes, as each cluster has its own unique set of tooling and patterns. We do provide examples to help you get started though. Check out -[this example](https://github.com/spotify/backstage/tree/master/contrib/kubernetes/plain_single_backend_deplyoment/) +[this example](https://github.com/backstage/backstage/tree/master/contrib/kubernetes/plain_single_backend_deployment/) for a basic single-deployment setup. diff --git a/docs/getting-started/deployment-other.md b/docs/getting-started/deployment-other.md index 3e06e17c77..cfd2e903d9 100644 --- a/docs/getting-started/deployment-other.md +++ b/docs/getting-started/deployment-other.md @@ -23,7 +23,7 @@ Then open http://localhost/ on your browser. Deploying to Heroku is relatively easy following these steps. First, make sure you have the -[heroku CLI installed](https://devcenter.heroku.com/articles/heroku-cli) and log +[Heroku CLI installed](https://devcenter.heroku.com/articles/heroku-cli) and log into it as well as login into Heroku's [container registry](https://devcenter.heroku.com/articles/container-registry-and-runtime). @@ -32,7 +32,7 @@ $ heroku login $ heroku container:login ``` -You _might_ also need to set your Heroku app's stack to `container` +You _might_ also need to set your Heroku app's stack to `container`. ```bash $ heroku stack:set container -a diff --git a/docs/getting-started/development-environment.md b/docs/getting-started/development-environment.md index aa9aa0bde1..c5275114ce 100644 --- a/docs/getting-started/development-environment.md +++ b/docs/getting-started/development-environment.md @@ -56,7 +56,7 @@ system resources and slow things down. ## Package Scripts There are many commands to be found in the root -[package.json](https://github.com/spotify/backstage/blob/master/package.json), +[package.json](https://github.com/backstage/backstage/blob/master/package.json), here are some useful ones: ```python @@ -86,7 +86,7 @@ yarn create-plugin # Create a new plugin ``` > See -> [package.json](https://github.com/spotify/backstage/blob/master/package.json) +> [package.json](https://github.com/backstage/backstage/blob/master/package.json) > for other yarn commands/options. ## Local configuration diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 4ca2f431a7..7fc80b625c 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -23,8 +23,8 @@ Requests towards this repo. Backstage provides the `@backstage/create-app` package to scaffold standalone instances of Backstage. You will need to have -[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed -(currently v12), [yarn](https://classic.yarnpkg.com/en/docs/install) and +[Node.js](https://nodejs.org/en/download/) Active LTS Release installed +(currently v14), [Yarn](https://classic.yarnpkg.com/en/docs/install) and [Python](https://www.python.org/downloads/) (although you likely have it already). You will also need to have [Docker](https://docs.docker.com/engine/install/) installed to use some features @@ -38,13 +38,13 @@ npx @backstage/create-app ``` You will be taken through a wizard to create your app, and the output should -look something like this. You can read more about this process -[here](https://backstage.io/docs/getting-started/create-an-app). +look something like this. You can read more about this process in +[Create an app](https://backstage.io/docs/getting-started/create-an-app). ### Contributing to Backstage You can read more in our -[CONTRIBUTING](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md) +[CONTRIBUTING](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md) guide, which can help you get setup with a Backstage development environment. ### Next steps diff --git a/docs/getting-started/running-backstage-locally.md b/docs/getting-started/running-backstage-locally.md index 6e6c8b2733..a30a918fd0 100644 --- a/docs/getting-started/running-backstage-locally.md +++ b/docs/getting-started/running-backstage-locally.md @@ -8,7 +8,7 @@ description: Documentation on How to run Backstage Locally - Node.js -First make sure you are using NodeJS with an Active LTS Release, currently v12. +First make sure you are using Node.js with an Active LTS Release, currently v12. This is made easy with a version manager such as [nvm](https://github.com/nvm-sh/nvm) which allows for version switching. @@ -23,10 +23,10 @@ node --version > v12.18.3 ``` -- yarn +- Yarn Please refer to the -[installation instructions for yarn](https://classic.yarnpkg.com/en/docs/install/). +[installation instructions for Yarn](https://classic.yarnpkg.com/en/docs/install/). - Docker @@ -42,7 +42,7 @@ of GitHub and run an initial build. ```bash # Start from your local development folder -git clone --depth 1 git@github.com:spotify/backstage.git +git clone --depth 1 git@github.com:backstage/backstage.git cd backstage # Fetch our dependencies and run an initial build @@ -84,19 +84,19 @@ exploring. But you can also set up any of the available authentication methods. The easiest option will be GitHub. To setup GitHub authentication in Backstage, see -[these instructions](https://github.com/spotify/backstage/tree/master/plugins/auth-backend#github). +[these instructions](https://github.com/backstage/backstage/tree/master/plugins/auth-backend#github). --- Congratulations! That should be it. Let us know how it went [on discord](https://discord.gg/EBHEGzX), file issues for any -[feature](https://github.com/spotify/backstage/issues/new?labels=help+wanted&template=feature_template.md) +[feature](https://github.com/backstage/backstage/issues/new?labels=help+wanted&template=feature_template.md) or -[plugin suggestions](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME), +[plugin suggestions](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME), or -[bugs](https://github.com/spotify/backstage/issues/new?labels=bug&template=bug_template.md) +[bugs](https://github.com/backstage/backstage/issues/new?labels=bug&template=bug_template.md) you have, and feel free to -[contribute](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md)! +[contribute](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md)! ## Creating a Plugin diff --git a/docs/openapi/definitions/auth.yaml b/docs/openapi/definitions/auth.yaml index cb736fd2a9..411ce69253 100644 --- a/docs/openapi/definitions/auth.yaml +++ b/docs/openapi/definitions/auth.yaml @@ -12,14 +12,14 @@ info: The API is supplied with a list of providers - such as `Google` or `Github` - and will add the endpoints described below to each of those providers. - Read more about [User Authentication and Authorization in Backstage](https://github.com/spotify/backstage/blob/master/docs/auth/overview.md). + Read more about [User Authentication and Authorization in Backstage](https://github.com/backstage/backstage/blob/master/docs/auth/overview.md). license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html version: 0.1.1-alpha.8 externalDocs: description: Backstage official documentation - url: https://github.com/spotify/backstage/blob/master/docs/README.md + url: https://github.com/backstage/backstage/blob/master/docs/README.md servers: - url: http://localhost:7000/api/auth/ tags: diff --git a/docs/overview/adopting.md b/docs/overview/adopting.md index 422adfb288..0d404d5cb4 100644 --- a/docs/overview/adopting.md +++ b/docs/overview/adopting.md @@ -42,7 +42,7 @@ infra/platform teams and end-users: ![pop](../assets/pop.png) While anyone at your company can contribute to the platform, the vast majority -of work will be done by teams that also has internal engineers as their +of work will be done by teams that also have internal engineers as their customers. The central team should treat these _contributing teams_ as customers of the platform as well. @@ -51,9 +51,9 @@ customers. This is done primarily by building [plugins](../plugins/index.md). Contributing teams should themselves treat their plugins as, or part of, the products they maintain. -> Case study: Inside Spotify we have a team that owns our CI platform. They -> don't only maintain the pipelines and build servers, but also expose their -> product in Backstage through a plugin. Since they also +> Case study: Inside Spotify we have a team that owns our CI platform. They not +> only maintain the pipelines and build servers, but also expose their product +> in Backstage through a plugin. Since they also > [maintain their own API](../plugins/call-existing-api.md), they can improve > their product by iterating on API and UI in lockstep. Because the plugin > follows our [platform design guidelines](../dls/design.md) their customers get @@ -123,14 +123,14 @@ successful impact on your software development process: engineer is someone that is able to contribute to different domains of engineering. Teams with T-shaped people have fewer bottlenecks and can therefore deliver more consistently. Backstage makes it easier to be T-shaped - since tools and infrastructure is consistent between domains, and information + since tools and infrastructure are consistent between domains, and information is available centrally. - **eNPS** Surveys asking about how productive people feel, how easy it is to find information and overall satisfaction with internal tools. - **Fragmentation** _(Experimental)_ Backstage - [Software Templates](../features/software-templates/index.md) helps drive + [Software Templates](../features/software-templates/index.md) help drive standardization in your software ecosystem. By measuring the variance in technology between different software components it is possible to get a sense of the overall fragmentation in your ecosystem. Examples could include: diff --git a/docs/overview/architecture-overview.md b/docs/overview/architecture-overview.md index 8edf3e9e4c..d8069c8665 100644 --- a/docs/overview/architecture-overview.md +++ b/docs/overview/architecture-overview.md @@ -24,7 +24,7 @@ different ways. ## Overview The following diagram shows how Backstage might look when deployed inside a -company which uses the Tech Radar plugin, the Lighthouse plugin, the Circle CI +company which uses the Tech Radar plugin, the Lighthouse plugin, the CircleCI plugin and the service catalog. There are 3 main components in this architecture: @@ -39,7 +39,7 @@ this. ![The architecture of a basic Backstage application](../assets/architecture-overview/backstage-typical-architecture.png) -## The UI +## User Interface The UI is a thin, client-side wrapper around a set of plugins. It provides some core UI components and libraries for shared activities such as config @@ -48,14 +48,14 @@ management. [[live demo](https://backstage-demo.roadie.io/)] ![UI with different components highlighted](../assets/architecture-overview/core-vs-plugin-components-highlighted.png) Each plugin typically makes itself available in the UI on a dedicated URL. For -example, the lighthouse plugin is registered with the UI on `/lighthouse`. +example, the Lighthouse plugin is registered with the UI on `/lighthouse`. [[live demo](https://backstage-demo.roadie.io/lighthouse)] ![The lighthouse plugin UI](../assets/architecture-overview/lighthouse-plugin.png) -The Circle CI plugin is available on `/circleci`. +The CircleCI plugin is available on `/circleci`. -![Circle CI Plugin UI](../assets/architecture-overview/circle-ci.png) +![CircleCI Plugin UI](../assets/architecture-overview/circle-ci.png) ## Plugins and plugin backends @@ -63,20 +63,20 @@ Each plugin is a client side application which mounts itself on the UI. Plugins are written in TypeScript or JavaScript. They each live in their own directory in `backstage/plugins`. For example, the source code for the lighthouse plugin is available at -[backstage/plugins/lighthouse](https://github.com/spotify/backstage/tree/master/plugins/lighthouse). +[backstage/plugins/lighthouse](https://github.com/backstage/backstage/tree/master/plugins/lighthouse). ### Installing plugins Plugins are typically loaded by the UI in your Backstage applications `plugins.ts` file. For example, -[here](https://github.com/spotify/backstage/blob/master/packages/app/src/plugins.ts) +[here](https://github.com/backstage/backstage/blob/master/packages/app/src/plugins.ts) is that file in the Backstage sample app. Plugins can be enabled, and passed configuration in `apis.ts`. For example, -[here](https://github.com/spotify/backstage/blob/master/packages/app/src/apis.ts) +[here](https://github.com/backstage/backstage/blob/master/packages/app/src/apis.ts) is that file in the Backstage sample app. -This is how the lighthouse plugin would be enabled in a typical Backstage +This is how the Lighthouse plugin would be enabled in a typical Backstage application: ```tsx @@ -108,7 +108,7 @@ Architecturally, plugins can take three forms: #### Standalone plugins Standalone plugins run entirely in the browser. -[The tech radar plugin](https://backstage-demo.roadie.io/tech-radar), for +[The Tech Radar plugin](https://backstage-demo.roadie.io/tech-radar), for example, simply renders hard-coded information. It doesn't make any API requests to other services. @@ -124,9 +124,9 @@ simple. Service backed plugins make API requests to a service which is within the purview of the organisation running Backstage. -The lighthouse plugin, for example, makes requests to the +The Lighthouse plugin, for example, makes requests to the [lighthouse-audit-service](https://github.com/spotify/lighthouse-audit-service). -The lighthouse-audit-service is a microservice which runs a copy of Google's +The `lighthouse-audit-service` is a microservice which runs a copy of Google's [Lighthouse library](https://github.com/GoogleChrome/lighthouse/) and stores the results in a PostgreSQL database. @@ -144,43 +144,44 @@ Third-party backed plugins are similar to service backed plugins. The main difference is that the service which backs the plugin is hosted outside of the ecosystem of the company hosting Backstage. -The Circle CI plugin is an example of a third-party backed plugin. Circle CI is -a SaaS service which can be used without any knowledge of Backstage. It has an -API which a Backstage plugin consumes to display content. +The CircleCI plugin is an example of a third-party backed plugin. CircleCI is a +SaaS service which can be used without any knowledge of Backstage. It has an API +which a Backstage plugin consumes to display content. -Requests which go to Circle CI from the users browser are passed through a proxy +Requests going to CircleCI from the user's browser are passed through a proxy service that Backstage provides. Without this, the requests would be blocked by Cross Origin Resource Sharing policies which prevent a browser page served at [https://example.com](https://example.com) from serving resources hosted at https://circleci.com. -![CircleCi plugin talking to proxy talking to SaaS Circle CI](../assets/architecture-overview/circle-ci-plugin-architecture.png) +![CircleCI plugin talking to proxy talking to SaaS Circle CI](../assets/architecture-overview/circle-ci-plugin-architecture.png) ## Databases -As we have seen, both the lighthouse-audit-service and catalog-backend require a -database to work with. +As we have seen, both the `lighthouse-audit-service` and `catalog-backend` +require a database to work with. -At the time of writing, the lighthouse-audit-service requires PostgreSQL to work -with. The service catalog backend uses an in-memory Sqlite3 instance. This is a -development oriented setup and there are plans to support other databases in the -future. +The Backstage backend and its builtin plugins are based on the +[Knex](http://knexjs.org/) library, and set up a separate logical database per +plugin. This gives great isolation and lets them perform migrations and evolve +separate from each other. -To learn more about the future of databases and Backstage, see the following two -GitHub issues. - -[Knex + Plugins (Multiple vs Single Database) · Issue #1598 · spotify/backstage](https://github.com/spotify/backstage/issues/1598) - -[Update migrations to support postgres by dariddler · Pull Request #1527 · spotify/backstage](https://github.com/spotify/backstage/pull/1527#discussion_r450374145) +The Knex library supports a multitude of databases, but Backstage is at the time +of writing tested primarily against two of them: SQLite, which is mainly used as +an in-memory mock/test database, and PostgreSQL, which is the preferred +production database. Other databases such as the MySQL variants are reported to +work but +[aren't tested as fully](https://github.com/backstage/backstage/issues/2460) +yet. ## Containerization The example Backstage architecture shown above would Dockerize into three -separate docker images. +separate Docker images. 1. The frontend container 2. The backend container -3. The lighthouse audit service container +3. The Lighthouse audit service container ![Boxes around the architecture to indicate how it is containerised](../assets/architecture-overview/containerised.png) @@ -204,7 +205,7 @@ yarn run docker-build This will create a container called `example-backend`. The lighthouse-audit-service container is already publicly available in Docker -Hub and can be downloaded and ran with +Hub and can be downloaded and run with ```bash docker run spotify/lighthouse-audit-service:latest diff --git a/docs/overview/logos.md b/docs/overview/logos.md index 2a684420bc..4c0c345f36 100644 --- a/docs/overview/logos.md +++ b/docs/overview/logos.md @@ -8,7 +8,7 @@ description: Guidelines for how to use the Backstage logos and icons Guidelines for how to use the Backstage logo and icon can be found [here](/logo_assets/Backstage_Identity_Assets_Overview.pdf). The assets below are all in `.svg` format. Other formats are available in the -[repository](https://github.com/spotify/backstage/tree/master/microsite/static/logo_assets). +[repository](https://github.com/backstage/backstage/tree/master/microsite/static/logo_assets). ## Backstage logo diff --git a/docs/overview/roadmap.md b/docs/overview/roadmap.md index 51f09347ce..71612cc5e4 100644 --- a/docs/overview/roadmap.md +++ b/docs/overview/roadmap.md @@ -9,8 +9,8 @@ description: Roadmap of Backstage Project > Backstage is currently under rapid development. This means that you can expect > APIs and features to evolve. It is also recommended that teams who adopt > Backstage today upgrade their installation as new -> [releases](https://github.com/spotify/backstage/releases) become available, as -> Backwards compatibility is not yet guaranteed. +> [releases](https://github.com/backstage/backstage/releases) become available, +> as Backwards compatibility is not yet guaranteed. ## Phases @@ -37,34 +37,34 @@ We have divided the project into three high-level _phases_: If you have questions about the roadmap or want to provide feedback, we would love to hear from you! Please create an -[Issue](https://github.com/spotify/backstage/issues/new/choose), ping us on +[Issue](https://github.com/backstage/backstage/issues/new/choose), ping us on [Discord](https://discord.gg/EBHEGzX) or reach out directly at -[alund@spotify.com](mailto:alund@spotify.com). +[backstage-interest@spotify.com](mailto:backstage-interest@spotify.com). Want to help out? Awesome ❤️ Head over to -[CONTRIBUTING](https://github.com/spotify/backstage/blob/master/CONTRIBUTING.md) +[CONTRIBUTING](https://github.com/backstage/backstage/blob/master/CONTRIBUTING.md) guidelines to get started. ### Ongoing work 🚧 -- **[Plugins for managing micro services end-2-end](https://github.com/spotify/backstage/milestone/14)** +- **[Plugins for managing micro services end-2-end](https://github.com/backstage/backstage/milestone/14)** Out of the box Backstage will ship with a set of plugins (Overview, CI, API and Docs) that will demonstrate how a user can manage a micro service and follow a change all the way out in production. Completing this work will make it much easier to see how a plugin can be built that integrates with the Backstage Service Catalog. -- **[Users and teams](https://github.com/spotify/backstage/issues/1807)** +- **[Users and teams](https://github.com/backstage/backstage/issues/1807)** Ownership is a central concept in Backstage. It should be easy to import your existing organizational data, such as users and groups/teams, into Backstage. A user the logs into Backstage should see software components owned by the team(s) they are in. -- **[Backstage platform is stable](https://github.com/spotify/backstage/milestone/19)** - +- **[Backstage platform is stable](https://github.com/backstage/backstage/milestone/19)** - The platform APIs and features are stable and can be depended on for production use. After this plugins will require little to no maintenance. -* **[Improved Kubernetes plugin](https://github.com/spotify/backstage/issues/2857)** - +* **[Improved Kubernetes plugin](https://github.com/backstage/backstage/issues/2857)** - Native support for Kubernetes, making it easier for developers to see and manage their services running in k8s. @@ -77,21 +77,21 @@ guidelines to get started. deployment available publicly so that people can click around and get a feel for the product without having to install anything. -- **[Global search](https://github.com/spotify/backstage/issues/1499)** - Extend - the basic search available in the Backstage Service Catalog with a global - search experience. Long term this search solution should be extensible, making - it possible for you add custom search results. +- **[Global search](https://github.com/backstage/backstage/issues/1499)** - + Extend the basic search available in the Backstage Service Catalog with a + global search experience. Long term this search solution should be extensible, + making it possible for you add custom search results. -- **[[TechDocs V.2] Stabilization release](https://github.com/spotify/backstage/milestone/17)** - +- **[[TechDocs V.2] Stabilization release](https://github.com/backstage/backstage/milestone/17)** - Platform stability and compatibility improvements. - **Additional auth providers** - Backstage should work for most (all!) auth solutions. Since Backstage can be used by companies regardless of what cloud (or on prem) you are using we are especially keen to get auth support for - [AWS](https://github.com/spotify/backstage/issues/290), - [Azure](https://github.com/spotify/backstage/issues/348) and others. + [AWS](https://github.com/backstage/backstage/issues/290), + [Azure](https://github.com/backstage/backstage/issues/348) and others. -- **[Initial GraphQL API](https://github.com/spotify/backstage/milestone/13)** - +- **[Initial GraphQL API](https://github.com/backstage/backstage/milestone/13)** - A GraphQL API will open up the rich metadata provided by Backstage in a single query. Plugins can easily query this API as well as extend the model where needed. @@ -102,18 +102,18 @@ Building and maintaining [plugins](https://backstage.io/plugins) is the work of the entire Backstage community. A list of plugins that are in development is -[available here](https://github.com/spotify/backstage/issues?q=is%3Aissue+is%3Aopen+label%3Aplugin+sort%3Areactions-%2B1-desc). +[available here](https://github.com/backstage/backstage/issues?q=is%3Aissue+is%3Aopen+label%3Aplugin+sort%3Areactions-%2B1-desc). We strongly recommend to upvote 👍 plugins you are interested in. This helps us and the community prioritize what plugins to build. Are you missing a plugin for your favorite tool? Please -[suggest a new one](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). +[suggest a new one](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). Chances are that someone will jump in and help build it. ### Completed milestones ✅ -- [Kubernetes plugin - v1](https://github.com/spotify/backstage/tree/master/plugins/kubernetes) -- [Helm charts](https://github.com/spotify/backstage/tree/master/contrib/chart/backstage) +- [Kubernetes plugin - v1](https://github.com/backstage/backstage/tree/master/plugins/kubernetes) +- [Helm charts](https://github.com/backstage/backstage/tree/master/contrib/chart/backstage) - [Backstage Design System 💅](https://backstage.io/blog/2020/09/30/backstage-design-system) - [Cost Insights plugin 💸](https://engineering.atspotify.com/2020/09/29/managing-clouds-from-the-ground-up-cost-engineering-at-spotify/) - [Donate Backstage to the CNCF 🎉](https://backstage.io/blog/2020/09/23/backstage-cncf-sandbox) @@ -123,11 +123,11 @@ Chances are that someone will jump in and help build it. - [Backstage Service 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/spotify/backstage/milestone/15) +- [TechDocs v0](https://github.com/backstage/backstage/milestone/15) - CI plugins: CircleCI, Jenkins, GitHub Actions and TravisCI -- [Service API documentation](https://github.com/spotify/backstage/pull/1737) +- [Service API documentation](https://github.com/backstage/backstage/pull/1737) - Backstage Service Catalog can read from: GitHub, GitLab, - [Bitbucket](https://github.com/spotify/backstage/pull/1938) + [Bitbucket](https://github.com/backstage/backstage/pull/1938) - Support auth providers: Google, Okta, GitHub, GitLab, - [auth0](https://github.com/spotify/backstage/pull/1611), - [AWS](https://github.com/spotify/backstage/pull/1990) + [auth0](https://github.com/backstage/backstage/pull/1611), + [AWS](https://github.com/backstage/backstage/pull/1990) diff --git a/docs/overview/vision.md b/docs/overview/vision.md index df75a4f0a6..c17e2b17ba 100644 --- a/docs/overview/vision.md +++ b/docs/overview/vision.md @@ -19,5 +19,5 @@ We are working on making Backstage the trusted standard toolbox (read: UX layer) for the open source infrastructure landscape. Think of it like Kubernetes for developer experience. We realize this is an ambitious goal. We can’t do it alone. If this sounds interesting or you'd like to help us shape our product -vision, we'd love to talk. You can email me directly: -[alund@spotify.com](mailto:alund@spotify.com). +vision, we'd love to talk. You can email us directly: +[backstage-interest@spotify.com](mailto:backstage-interest@spotify.com). diff --git a/docs/overview/what-is-backstage.md b/docs/overview/what-is-backstage.md index 3d41c714ee..5439b838bd 100644 --- a/docs/overview/what-is-backstage.md +++ b/docs/overview/what-is-backstage.md @@ -30,7 +30,7 @@ Out of the box, Backstage includes: code" approach - Plus, a growing ecosystem of - [open source plugins](https://github.com/spotify/backstage/tree/master/plugins) + [open source plugins](https://github.com/backstage/backstage/tree/master/plugins) that further expand Backstage’s customizability and functionality ## Backstage and the CNCF diff --git a/docs/plugins/add-to-marketplace.md b/docs/plugins/add-to-marketplace.md index 59cca07bff..790512e6aa 100644 --- a/docs/plugins/add-to-marketplace.md +++ b/docs/plugins/add-to-marketplace.md @@ -8,7 +8,7 @@ description: Documentation on Adding Plugin to Marketplace To add a new plugin to the [plugin marketplace](https://backstage.io/plugins) create a file in -[`microsite/data/plugins`](https://github.com/spotify/backstage/tree/master/microsite/data/plugins) +[`microsite/data/plugins`](https://github.com/backstage/backstage/tree/master/microsite/data/plugins) with your plugin's information. Example: ```yaml diff --git a/docs/plugins/call-existing-api.md b/docs/plugins/call-existing-api.md index 14ea4c1f5a..75e054d2b9 100644 --- a/docs/plugins/call-existing-api.md +++ b/docs/plugins/call-existing-api.md @@ -88,7 +88,7 @@ The proxy is powered by the `http-proxy-middleware` package. See [Proxying](proxying.md) for a full description of its configuration options. Internally at Spotify, the proxy option has been the overwhelmingly most popular -choice for plugin makers. Since we have DNS based service discovery in place and +choice for plugin makers. Since we have DNS-based service discovery in place and a microservices framework that made it trivial to expose plain HTTP, it has been a matter of just adding a few lines of Backstage config to get the benefit of being easily and robustly reachable from users' web browsers as well. @@ -137,7 +137,7 @@ router.use('/summary', async (req, res) => { ``` For a more detailed example, see -[the lighthouse plugin](https://github.com/spotify/backstage/tree/master/plugins/lighthouse) +[the lighthouse plugin](https://github.com/backstage/backstage/tree/master/plugins/lighthouse) that stores some state in a database and adds new capabilities to the underlying API. diff --git a/docs/plugins/index.md b/docs/plugins/index.md index 8836c1cd42..dcef3f995c 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -22,7 +22,7 @@ To create a plugin, follow the steps outlined [here](create-a-plugin.md). If you start developing a plugin that you aim to release as open source, we suggest that you create a -[new Issue](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). +[new Issue](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). 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 diff --git a/docs/plugins/publishing.md b/docs/plugins/publishing.md index fbeab6340c..7eab61891e 100644 --- a/docs/plugins/publishing.md +++ b/docs/plugins/publishing.md @@ -7,7 +7,7 @@ description: Documentation on Publishing NPM packages ## NPM NPM packages are published through CI/CD in the -[.github/workflows/master.yml](https://github.com/spotify/backstage/blob/master/.github/workflows/master.yml) +[.github/workflows/master.yml](https://github.com/backstage/backstage/blob/master/.github/workflows/master.yml) workflow. Every commit that is merged to master will be checked for new versions of all public packages, and any new versions will automatically be published to NPM. @@ -56,5 +56,3 @@ $ git reset --hard master $ yarn release $ git push --force ``` - -[Back to Docs](../README.md) diff --git a/docs/plugins/structure-of-a-plugin.md b/docs/plugins/structure-of-a-plugin.md index ee0a27cde2..3f631a9a46 100644 --- a/docs/plugins/structure-of-a-plugin.md +++ b/docs/plugins/structure-of-a-plugin.md @@ -73,7 +73,7 @@ export const plugin = createPlugin({ ``` This is where the plugin is created and where it hooks into the app by declaring -what component should be shown on what url. See reference docs for +what component should be shown on what URL. See reference docs for [createPlugin](../reference/createPlugin.md) or [router](../reference/createPlugin-router.md). @@ -101,11 +101,11 @@ Backstage CLI. ## Talking to the outside world -If your plugin needs to communicate with services outside the backstage +If your plugin needs to communicate with services outside the Backstage environment you will probably face challenges like CORS policies and/or backend-side authorization. To smooth this process out you can use proxy - -either the one you already have (like nginx/haproxy/etc) or the proxy-backend -plugin that we provide for the backstage backend. -[Read more](https://github.com/spotify/backstage/blob/master/plugins/proxy-backend/README.md) +either the one you already have (like Nginx, HAProxy, etc.) or the proxy-backend +plugin that we provide for the Backstage backend. +[Read more](https://github.com/backstage/backstage/blob/master/plugins/proxy-backend/README.md) [Back to Getting Started](../README.md) diff --git a/docs/plugins/testing.md b/docs/plugins/testing.md index c6e1599786..e60b5fa8b7 100644 --- a/docs/plugins/testing.md +++ b/docs/plugins/testing.md @@ -248,15 +248,15 @@ Testing an API involves verifying four things: ### Mocking API Calls -[Mocking in jest](https://facebook.github.io/jest/docs/en/mock-functions.html) +[Mocking in Jest](https://facebook.github.io/jest/docs/en/mock-functions.html) involves wrapping existing functions (like an API call function) with an alternative. For example: -**./Api.js** +**`./MyApi.js`** -``` +```js export { fetchSomethingFromServer: () => { // Live production call to a URI. Must be avoided during testing! @@ -265,9 +265,9 @@ export { }; ``` -**./\_\_mocks\_\_/Api.js** +**`./\_\_mocks\_\_/MyApi.js`** -``` +```js export { fetchSomethingFromServer: () => { // Simulate a production call, but avoid jest and just use a promise @@ -276,16 +276,16 @@ export { } ``` -**./Api.test.js** +**`./MyApi.test.js`** -``` +```js /* eslint-disable import/first */ jest.mock('./MyApi'); // Instruct Jest to swap all future imports of './MyApi.js' to './__mocks__/MyApi.js' import MyApi from './MyApi'; // Will actually return the contents of the file in the __mocks__ folder now -it ('loads data', (done) => { +it('loads data', done => { MyApi.fetchSomethingFromServer().then(result => { expect(result).toBe('some result object simulating server data here'); done(); diff --git a/docs/reference/createPlugin-feature-flags.md b/docs/reference/createPlugin-feature-flags.md index ebb8a6b503..bcea80e26b 100644 --- a/docs/reference/createPlugin-feature-flags.md +++ b/docs/reference/createPlugin-feature-flags.md @@ -8,12 +8,6 @@ The `featureFlags` object passed to the `register` function makes it possible for plugins to register Feature Flags in Backstage for users to opt into. You can use this to split out logic in your code for manual A/B testing, etc. -```typescript -export type FeatureFlagsHooks = { - register(name: FeatureFlagName): void; -}; -``` - Here's a code sample: ```typescript @@ -21,8 +15,7 @@ import { createPlugin } from '@backstage/core'; export default createPlugin({ id: 'welcome', - register({ router, featureFlags }) { - // router.registerRoute('/', Component); + register({ featureFlags }) { featureFlags.register('enable-example-feature'); }, }); @@ -30,41 +23,22 @@ export default createPlugin({ ## Using with useApi -To use it, you'll first need to register the `FeatureFlags` API via -`ApiRegistry` in your `apis.ts` in your App: - -```tsx -import { - ApiHolder, - ApiRegistry, - featureFlagsApiRef, - FeatureFlags, -} from '@backstage/core'; - -const builder = ApiRegistry.builder(); -builder.add(featureFlagsApiRef, new FeatureFlags()); - -export default builder.build() as ApiHolder; -``` - -Then, later, you can directly use it via `useApi`: +To inspect the state of a feature flag inside your plugin, you can use the +`FeatureFlagsApi`, accessed via the `featureFlagsApiRef`. For example: ```tsx import React, { FC } from 'react'; import { Button } from '@material-ui/core'; -import { FeatureFlagState, featureFlagsApiRef, useApi } from '@backstage/core'; +import { featureFlagsApiRef, useApi } from '@backstage/core'; -const ExampleButton: FC<{}> = () => { - const flags = useApi(featureFlagsApiRef).getFlags(); - - const handleClick = () => { - flags.set('enable-example-feature', FeatureFlagState.On); - }; +const ExamplePage = () => { + const featureFlags = useApi(featureFlagsApiRef); return ( - +
+ + { featureFlags.isActive('enable-example-feature') && } +
); }; ``` diff --git a/docs/reference/utility-apis/AlertApi.md b/docs/reference/utility-apis/AlertApi.md index 6219f520f5..4116e964ae 100644 --- a/docs/reference/utility-apis/AlertApi.md +++ b/docs/reference/utility-apis/AlertApi.md @@ -1,7 +1,7 @@ # AlertApi The AlertApi type is defined at -[packages/core-api/src/apis/definitions/AlertApi.ts:29](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/AlertApi.ts#L29). +[packages/core-api/src/apis/definitions/AlertApi.ts:29](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/AlertApi.ts#L29). The following Utility API implements this type: [alertApiRef](./README.md#alert) @@ -38,7 +38,7 @@ export type AlertMessage = { Defined at -[packages/core-api/src/apis/definitions/AlertApi.ts:19](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/AlertApi.ts#L19). +[packages/core-api/src/apis/definitions/AlertApi.ts:19](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/AlertApi.ts#L19). Referenced by: [post](#post), [alert\$](#alert). @@ -67,13 +67,13 @@ export type Observable<T> = { Defined at -[packages/core-api/src/types.ts:53](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L53). +[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L53). Referenced by: [alert\$](#alert). ### Observer -This file contains non-react related core types used through Backstage. +This file contains non-react related core types used throughout Backstage. Observer interface for consuming an Observer, see TC39. @@ -86,7 +86,7 @@ export type Observer<T> = { Defined at -[packages/core-api/src/types.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L24). +[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L24). Referenced by: [Observable](#observable). @@ -109,6 +109,6 @@ export type Subscription = { Defined at -[packages/core-api/src/types.ts:33](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L33). +[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L33). Referenced by: [Observable](#observable). diff --git a/docs/reference/utility-apis/AppThemeApi.md b/docs/reference/utility-apis/AppThemeApi.md index eb35eb38ef..0f5c095825 100644 --- a/docs/reference/utility-apis/AppThemeApi.md +++ b/docs/reference/utility-apis/AppThemeApi.md @@ -1,7 +1,7 @@ # AppThemeApi The AppThemeApi type is defined at -[packages/core-api/src/apis/definitions/AppThemeApi.ts:50](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/AppThemeApi.ts#L50). +[packages/core-api/src/apis/definitions/AppThemeApi.ts:56](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/AppThemeApi.ts#L56). The following Utility API implements this type: [appThemeApiRef](./README.md#apptheme) @@ -72,11 +72,16 @@ export type AppTheme = { * The specialized MaterialUI theme instance. */ theme: BackstageTheme; + + /** + * An Icon for the theme mode setting. + */ + icon?: React.ReactElement<SvgIconProps>; } Defined at -[packages/core-api/src/apis/definitions/AppThemeApi.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/AppThemeApi.ts#L24). +[packages/core-api/src/apis/definitions/AppThemeApi.ts:25](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/AppThemeApi.ts#L25). Referenced by: [getInstalledThemes](#getinstalledthemes). @@ -87,7 +92,7 @@ export type BackstagePalette = Palette & Palette Defined at -[packages/theme/src/types.ts:70](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/theme/src/types.ts#L70). +[packages/theme/src/types.ts:74](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/theme/src/types.ts#L74). Referenced by: [BackstageTheme](#backstagetheme). @@ -96,11 +101,13 @@ Referenced by: [BackstageTheme](#backstagetheme). 
 export interface BackstageTheme extends Theme {
   palette: BackstagePalette;
+  page: PageTheme;
+  getPageTheme: ({ themeId }: PageThemeSelector) => PageTheme;
 }
Defined at -[packages/theme/src/types.ts:73](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/theme/src/types.ts#L73). +[packages/theme/src/types.ts:81](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/theme/src/types.ts#L81). Referenced by: [AppTheme](#apptheme). @@ -129,13 +136,13 @@ export type Observable<T> = { Defined at -[packages/core-api/src/types.ts:53](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L53). +[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L53). Referenced by: [activeThemeId\$](#activethemeid). ### Observer -This file contains non-react related core types used through Backstage. +This file contains non-react related core types used throughout Backstage. Observer interface for consuming an Observer, see TC39. @@ -148,10 +155,38 @@ export type Observer<T> = { Defined at -[packages/core-api/src/types.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L24). +[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L24). Referenced by: [Observable](#observable). +### PageTheme + +
+export type PageTheme = {
+  colors: string[];
+  shape: string;
+  backgroundImage: string;
+}
+
+ +Defined at +[packages/theme/src/types.ts:103](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/theme/src/types.ts#L103). + +Referenced by: [BackstageTheme](#backstagetheme). + +### PageThemeSelector + +
+export type PageThemeSelector = {
+  themeId: string;
+}
+
+ +Defined at +[packages/theme/src/types.ts:77](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/theme/src/types.ts#L77). + +Referenced by: [BackstageTheme](#backstagetheme). + ### PaletteAdditions 
@@ -181,6 +216,8 @@ type PaletteAdditions = {
   navigation: {
     background: string;
     indicator: string;
+    color: string;
+    selectedColor: string;
   };
   tabbar: {
     indicator: string;
@@ -199,12 +236,14 @@ type PaletteAdditions = {
   banner: {
     info: string;
     error: string;
+    text: string;
+    link: string;
   };
 }
Defined at -[packages/theme/src/types.ts:23](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/theme/src/types.ts#L23). +[packages/theme/src/types.ts:23](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/theme/src/types.ts#L23). Referenced by: [BackstagePalette](#backstagepalette). @@ -227,6 +266,6 @@ export type Subscription = { Defined at -[packages/core-api/src/types.ts:33](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L33). +[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L33). Referenced by: [Observable](#observable). diff --git a/docs/reference/utility-apis/BackstageIdentityApi.md b/docs/reference/utility-apis/BackstageIdentityApi.md index 529b73c576..dafdb7d55f 100644 --- a/docs/reference/utility-apis/BackstageIdentityApi.md +++ b/docs/reference/utility-apis/BackstageIdentityApi.md @@ -1,7 +1,7 @@ # BackstageIdentityApi The BackstageIdentityApi type is defined at -[packages/core-api/src/apis/definitions/auth.ts:134](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L134). +[packages/core-api/src/apis/definitions/auth.ts:134](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L134). The following Utility APIs implement this type: @@ -19,6 +19,8 @@ The following Utility APIs implement this type: - [oktaAuthApiRef](./README.md#oktaauth) +- [samlAuthApiRef](./README.md#samlauth) + ## Members ### getBackstageIdentity() @@ -68,7 +70,7 @@ export type AuthRequestOptions = { Defined at -[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L40). +[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L40). Referenced by: [getBackstageIdentity](#getbackstageidentity). @@ -89,6 +91,6 @@ export type BackstageIdentity = { Defined at -[packages/core-api/src/apis/definitions/auth.ts:147](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L147). +[packages/core-api/src/apis/definitions/auth.ts:147](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L147). Referenced by: [getBackstageIdentity](#getbackstageidentity). diff --git a/docs/reference/utility-apis/Config.md b/docs/reference/utility-apis/Config.md index b54e122c03..2ae047a700 100644 --- a/docs/reference/utility-apis/Config.md +++ b/docs/reference/utility-apis/Config.md @@ -1,7 +1,7 @@ # Config The Config type is defined at -[packages/config/src/types.ts:32](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/config/src/types.ts#L32). +[packages/config/src/types.ts:32](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/config/src/types.ts#L32). The following Utility API implements this type: [configApiRef](./README.md#config) @@ -140,7 +140,7 @@ export type Config = { Defined at -[packages/config/src/types.ts:32](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/config/src/types.ts#L32). +[packages/config/src/types.ts:32](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/config/src/types.ts#L32). Referenced by: [getConfig](#getconfig), [getOptionalConfig](#getoptionalconfig), [getConfigArray](#getconfigarray), @@ -153,7 +153,7 @@ export type JsonArray = JsonValue[] Defined at -[packages/config/src/types.ts:18](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/config/src/types.ts#L18). +[packages/config/src/types.ts:18](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/config/src/types.ts#L18). Referenced by: [JsonValue](#jsonvalue). @@ -164,7 +164,7 @@ export type JsonObject = { [key in string]?: JsonValue Defined at -[packages/config/src/types.ts:17](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/config/src/types.ts#L17). +[packages/config/src/types.ts:17](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/config/src/types.ts#L17). Referenced by: [JsonValue](#jsonvalue). @@ -181,7 +181,7 @@ export type JsonValue = Defined at -[packages/config/src/types.ts:19](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/config/src/types.ts#L19). +[packages/config/src/types.ts:19](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/config/src/types.ts#L19). Referenced by: [get](#get), [getOptional](#getoptional), [JsonObject](#jsonobject), [JsonArray](#jsonarray), [Config](#config). diff --git a/docs/reference/utility-apis/DiscoveryApi.md b/docs/reference/utility-apis/DiscoveryApi.md index 24371c1729..ac278fdd97 100644 --- a/docs/reference/utility-apis/DiscoveryApi.md +++ b/docs/reference/utility-apis/DiscoveryApi.md @@ -1,7 +1,7 @@ # DiscoveryApi The DiscoveryApi type is defined at -[packages/core-api/src/apis/definitions/DiscoveryApi.ts:30](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L30). +[packages/core-api/src/apis/definitions/DiscoveryApi.ts:30](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L30). The following Utility API implements this type: [discoveryApiRef](./README.md#discovery) diff --git a/docs/reference/utility-apis/ErrorApi.md b/docs/reference/utility-apis/ErrorApi.md index 762d2016d5..93f4f9cd48 100644 --- a/docs/reference/utility-apis/ErrorApi.md +++ b/docs/reference/utility-apis/ErrorApi.md @@ -1,7 +1,7 @@ # ErrorApi The ErrorApi type is defined at -[packages/core-api/src/apis/definitions/ErrorApi.ts:53](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/ErrorApi.ts#L53). +[packages/core-api/src/apis/definitions/ErrorApi.ts:53](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/ErrorApi.ts#L53). The following Utility API implements this type: [errorApiRef](./README.md#error) @@ -41,7 +41,7 @@ type Error = { Defined at -[packages/core-api/src/apis/definitions/ErrorApi.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/ErrorApi.ts#L24). +[packages/core-api/src/apis/definitions/ErrorApi.ts:24](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/ErrorApi.ts#L24). Referenced by: [post](#post), [error\$](#error). @@ -58,7 +58,7 @@ export type ErrorContext = { Defined at -[packages/core-api/src/apis/definitions/ErrorApi.ts:33](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/ErrorApi.ts#L33). +[packages/core-api/src/apis/definitions/ErrorApi.ts:33](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/ErrorApi.ts#L33). Referenced by: [post](#post), [error\$](#error). @@ -87,13 +87,13 @@ export type Observable<T> = { Defined at -[packages/core-api/src/types.ts:53](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L53). +[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L53). Referenced by: [error\$](#error). ### Observer -This file contains non-react related core types used through Backstage. +This file contains non-react related core types used throughout Backstage. Observer interface for consuming an Observer, see TC39. @@ -106,7 +106,7 @@ export type Observer<T> = { Defined at -[packages/core-api/src/types.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L24). +[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L24). Referenced by: [Observable](#observable). @@ -129,6 +129,6 @@ export type Subscription = { Defined at -[packages/core-api/src/types.ts:33](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L33). +[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L33). Referenced by: [Observable](#observable). diff --git a/docs/reference/utility-apis/FeatureFlagsApi.md b/docs/reference/utility-apis/FeatureFlagsApi.md index 8fbcb794fb..529d2ac5dc 100644 --- a/docs/reference/utility-apis/FeatureFlagsApi.md +++ b/docs/reference/utility-apis/FeatureFlagsApi.md @@ -1,27 +1,20 @@ # FeatureFlagsApi The FeatureFlagsApi type is defined at -[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:41](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L41). +[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:60](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L60). The following Utility API implements this type: [featureFlagsApiRef](./README.md#featureflags) ## Members -### registeredFeatureFlags +### registerFlag() -Store a list of registered feature flags. +Registers a new feature flag. Once a feature flag has been registered it can be +toggled by users, and read back to enable or disable features. 
-registeredFeatureFlags: FeatureFlagsRegistryItem[]
-
- -### getFlags() - -Get a list of all feature flags from the current user. - -
-getFlags(): UserFlags
+registerFlag(flag: FeatureFlag): void
### getRegisteredFlags() @@ -29,5 +22,92 @@ getFlags(): UserFlags Get a list of all registered flags. 
-getRegisteredFlags(): FeatureFlagsRegistry
+getRegisteredFlags(): FeatureFlag[]
+ +### isActive() + +Whether the feature flag with the given name is currently activated for the +user. + +
+isActive(name: string): boolean
+
+ +### save() + +Save the user's choice of feature flag states. + +
+save(options: FeatureFlagsSaveOptions): void
+
+ +## Supporting types + +These types are part of the API declaration, but may not be unique to this API. + +### FeatureFlag + +The feature flags API is used to toggle functionality to users across plugins +and Backstage. + +Plugins can use this API to register feature flags that they have available for +users to enable/disable, and this API will centralize the current user's state +of which feature flags they would like to enable. + +This is ideal for Backstage plugins, as well as your own App, to trial +incomplete or unstable upcoming features. Although there will be a common +interface for users to enable and disable feature flags, this API acts as +another way to enable/disable. + +
+export type FeatureFlag = {
+  name: string;
+  pluginId: string;
+}
+
+ +Defined at +[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:31](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L31). + +Referenced by: [registerFlag](#registerflag), +[getRegisteredFlags](#getregisteredflags). + +### FeatureFlagState + +
+export enum FeatureFlagState {
+  None = 0,
+  Active = 1,
+}
+
+ +Defined at +[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:36](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L36). + +Referenced by: [FeatureFlagsSaveOptions](#featureflagssaveoptions). + +### FeatureFlagsSaveOptions + +Options to use when saving feature flags. + +
+export type FeatureFlagsSaveOptions = {
+  /**
+   * The new feature flag states to save.
+   */
+  states: Record<string, FeatureFlagState>;
+
+  /**
+   * Whether the saves states should be merged into the existing ones, or replace them.
+   *
+   * Defaults to false.
+   */
+  merge?: boolean;
+}
+
+ +Defined at +[packages/core-api/src/apis/definitions/FeatureFlagsApi.ts:44](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L44). + +Referenced by: [save](#save). diff --git a/docs/reference/utility-apis/IdentityApi.md b/docs/reference/utility-apis/IdentityApi.md index 5ee5c582b6..a88aaf0b8a 100644 --- a/docs/reference/utility-apis/IdentityApi.md +++ b/docs/reference/utility-apis/IdentityApi.md @@ -1,7 +1,7 @@ # IdentityApi The IdentityApi type is defined at -[packages/core-api/src/apis/definitions/IdentityApi.ts:22](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/IdentityApi.ts#L22). +[packages/core-api/src/apis/definitions/IdentityApi.ts:22](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/IdentityApi.ts#L22). The following Utility API implements this type: [identityApiRef](./README.md#identity) @@ -76,6 +76,6 @@ export type ProfileInfo = { Defined at -[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L162). +[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L162). Referenced by: [getProfile](#getprofile). diff --git a/docs/reference/utility-apis/OAuthApi.md b/docs/reference/utility-apis/OAuthApi.md index a489db76c5..79b55812ef 100644 --- a/docs/reference/utility-apis/OAuthApi.md +++ b/docs/reference/utility-apis/OAuthApi.md @@ -1,7 +1,7 @@ # OAuthApi The OAuthApi type is defined at -[packages/core-api/src/apis/definitions/auth.ts:67](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L67). +[packages/core-api/src/apis/definitions/auth.ts:67](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L67). The following Utility APIs implement this type: @@ -82,7 +82,7 @@ export type AuthRequestOptions = { Defined at -[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L40). +[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L40). Referenced by: [getAccessToken](#getaccesstoken). @@ -108,6 +108,6 @@ export type OAuthScope = string | string[] Defined at -[packages/core-api/src/apis/definitions/auth.ts:38](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L38). +[packages/core-api/src/apis/definitions/auth.ts:38](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L38). Referenced by: [getAccessToken](#getaccesstoken). diff --git a/docs/reference/utility-apis/OAuthRequestApi.md b/docs/reference/utility-apis/OAuthRequestApi.md index 1328aabeec..f1c2311ce9 100644 --- a/docs/reference/utility-apis/OAuthRequestApi.md +++ b/docs/reference/utility-apis/OAuthRequestApi.md @@ -1,7 +1,7 @@ # OAuthRequestApi The OAuthRequestApi type is defined at -[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:99](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L99). +[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:99](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L99). The following Utility API implements this type: [oauthRequestApiRef](./README.md#oauthrequest) @@ -73,7 +73,7 @@ export type AuthProvider = { Defined at -[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:27](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L27). +[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:27](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L27). Referenced by: [AuthRequesterOptions](#authrequesteroptions), [PendingAuthRequest](#pendingauthrequest). @@ -97,7 +97,7 @@ export type AuthRequester<AuthResponse> = ( Defined at -[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:66](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L66). +[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:66](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L66). Referenced by: [createAuthRequester](#createauthrequester). @@ -122,7 +122,7 @@ export type AuthRequesterOptions<AuthResponse> = { Defined at -[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:43](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L43). +[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:43](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L43). Referenced by: [createAuthRequester](#createauthrequester). @@ -151,13 +151,13 @@ export type Observable<T> = { Defined at -[packages/core-api/src/types.ts:53](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L53). +[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L53). Referenced by: [authRequest\$](#authrequest). ### Observer -This file contains non-react related core types used through Backstage. +This file contains non-react related core types used throughout Backstage. Observer interface for consuming an Observer, see TC39. @@ -170,7 +170,7 @@ export type Observer<T> = { Defined at -[packages/core-api/src/types.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L24). +[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L24). Referenced by: [Observable](#observable). @@ -205,7 +205,7 @@ export type PendingAuthRequest = { Defined at -[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:77](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L77). +[packages/core-api/src/apis/definitions/OAuthRequestApi.ts:77](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L77). Referenced by: [authRequest\$](#authrequest). @@ -228,6 +228,6 @@ export type Subscription = { Defined at -[packages/core-api/src/types.ts:33](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L33). +[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L33). Referenced by: [Observable](#observable). diff --git a/docs/reference/utility-apis/OpenIdConnectApi.md b/docs/reference/utility-apis/OpenIdConnectApi.md index efd79593d6..eaea530708 100644 --- a/docs/reference/utility-apis/OpenIdConnectApi.md +++ b/docs/reference/utility-apis/OpenIdConnectApi.md @@ -1,7 +1,7 @@ # OpenIdConnectApi The OpenIdConnectApi type is defined at -[packages/core-api/src/apis/definitions/auth.ts:99](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L99). +[packages/core-api/src/apis/definitions/auth.ts:99](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L99). The following Utility APIs implement this type: @@ -66,6 +66,6 @@ export type AuthRequestOptions = { Defined at -[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L40). +[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L40). Referenced by: [getIdToken](#getidtoken). diff --git a/docs/reference/utility-apis/ProfileInfoApi.md b/docs/reference/utility-apis/ProfileInfoApi.md index 402b5ba504..76d04045e8 100644 --- a/docs/reference/utility-apis/ProfileInfoApi.md +++ b/docs/reference/utility-apis/ProfileInfoApi.md @@ -1,7 +1,7 @@ # ProfileInfoApi The ProfileInfoApi type is defined at -[packages/core-api/src/apis/definitions/auth.ts:117](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L117). +[packages/core-api/src/apis/definitions/auth.ts:117](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L117). The following Utility APIs implement this type: @@ -19,6 +19,8 @@ The following Utility APIs implement this type: - [oktaAuthApiRef](./README.md#oktaauth) +- [samlAuthApiRef](./README.md#samlauth) + ## Members ### getProfile() @@ -65,7 +67,7 @@ export type AuthRequestOptions = { Defined at -[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L40). +[packages/core-api/src/apis/definitions/auth.ts:40](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L40). Referenced by: [getProfile](#getprofile). @@ -93,6 +95,6 @@ export type ProfileInfo = { Defined at -[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L162). +[packages/core-api/src/apis/definitions/auth.ts:162](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L162). Referenced by: [getProfile](#getprofile). diff --git a/docs/reference/utility-apis/README.md b/docs/reference/utility-apis/README.md index 71931a5d5a..1ef5b6197e 100644 --- a/docs/reference/utility-apis/README.md +++ b/docs/reference/utility-apis/README.md @@ -3,7 +3,7 @@ The following is a list of all Utility APIs defined by `@backstage/core`. They are available to use by plugins and components, and can be accessed using the `useApi` hook, also provided by `@backstage/core`. For more information, see -https://github.com/spotify/backstage/blob/master/docs/api/utility-apis.md. +https://github.com/backstage/backstage/blob/master/docs/api/utility-apis.md. ### alert @@ -12,7 +12,7 @@ Used to report alerts and forward them to the app Implemented type: [AlertApi](./AlertApi.md) ApiRef: -[alertApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/AlertApi.ts#L41) +[alertApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/AlertApi.ts#L41) ### appTheme @@ -21,7 +21,7 @@ API Used to configure the app theme, and enumerate options Implemented type: [AppThemeApi](./AppThemeApi.md) ApiRef: -[appThemeApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/AppThemeApi.ts#L74) +[appThemeApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/AppThemeApi.ts#L80) ### auth0Auth @@ -32,7 +32,7 @@ Implemented types: [OpenIdConnectApi](./OpenIdConnectApi.md), [BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) ApiRef: -[auth0AuthApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L275) +[auth0AuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L275) ### config @@ -41,7 +41,7 @@ Used to access runtime configuration Implemented type: [Config](./Config.md) ApiRef: -[configApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/ConfigApi.ts#L22) +[configApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/ConfigApi.ts#L22) ### discovery @@ -50,7 +50,7 @@ Provides service discovery of backend plugins Implemented type: [DiscoveryApi](./DiscoveryApi.md) ApiRef: -[discoveryApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L44) +[discoveryApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/DiscoveryApi.ts#L44) ### error @@ -59,7 +59,7 @@ Used to report errors and forward them to the app Implemented type: [ErrorApi](./ErrorApi.md) ApiRef: -[errorApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/ErrorApi.ts#L65) +[errorApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/ErrorApi.ts#L65) ### featureFlags @@ -68,7 +68,7 @@ Used to toggle functionality in features across Backstage Implemented type: [FeatureFlagsApi](./FeatureFlagsApi.md) ApiRef: -[featureFlagsApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L58) +[featureFlagsApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/FeatureFlagsApi.ts#L83) ### githubAuth @@ -79,7 +79,7 @@ Implemented types: [OAuthApi](./OAuthApi.md), [BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) ApiRef: -[githubAuthApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L232) +[githubAuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L232) ### gitlabAuth @@ -90,7 +90,7 @@ Implemented types: [OAuthApi](./OAuthApi.md), [BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) ApiRef: -[gitlabAuthApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L262) +[gitlabAuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L262) ### googleAuth @@ -102,7 +102,7 @@ Implemented types: [OAuthApi](./OAuthApi.md), [BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) ApiRef: -[googleAuthApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L215) +[googleAuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L215) ### identity @@ -111,7 +111,7 @@ Provides access to the identity of the signed in user Implemented type: [IdentityApi](./IdentityApi.md) ApiRef: -[identityApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/IdentityApi.ts#L54) +[identityApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/IdentityApi.ts#L54) ### microsoftAuth @@ -123,7 +123,7 @@ Implemented types: [OAuthApi](./OAuthApi.md), [BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) ApiRef: -[microsoftAuthApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L289) +[microsoftAuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L289) ### oauth2 @@ -135,7 +135,7 @@ Implemented types: [OAuthApi](./OAuthApi.md), [BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) ApiRef: -[oauth2ApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L303) +[oauth2ApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L303) ### oauthRequest @@ -144,7 +144,7 @@ An API for implementing unified OAuth flows in Backstage Implemented type: [OAuthRequestApi](./OAuthRequestApi.md) ApiRef: -[oauthRequestApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L130) +[oauthRequestApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/OAuthRequestApi.ts#L130) ### oktaAuth @@ -156,7 +156,17 @@ Implemented types: [OAuthApi](./OAuthApi.md), [BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) ApiRef: -[oktaAuthApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L245) +[oktaAuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L245) + +### samlAuth + +Example of how to use SAML custom provider + +Implemented types: [ProfileInfoApi](./ProfileInfoApi.md), +[BackstageIdentityApi](./BackstageIdentityApi.md), [SessionApi](./SessionApi.md) + +ApiRef: +[samlAuthApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L317) ### storage @@ -165,4 +175,4 @@ Provides the ability to store data which is unique to the user Implemented type: [StorageApi](./StorageApi.md) ApiRef: -[storageApiRef](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/StorageApi.ts#L68) +[storageApiRef](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/StorageApi.ts#L68) diff --git a/docs/reference/utility-apis/SessionApi.md b/docs/reference/utility-apis/SessionApi.md index e7a9e58c59..7d271558d6 100644 --- a/docs/reference/utility-apis/SessionApi.md +++ b/docs/reference/utility-apis/SessionApi.md @@ -1,7 +1,7 @@ # SessionApi The SessionApi type is defined at -[packages/core-api/src/apis/definitions/auth.ts:190](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L190). +[packages/core-api/src/apis/definitions/auth.ts:190](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L190). The following Utility APIs implement this type: @@ -19,6 +19,8 @@ The following Utility APIs implement this type: - [oktaAuthApiRef](./README.md#oktaauth) +- [samlAuthApiRef](./README.md#samlauth) + ## Members ### signIn() @@ -75,13 +77,13 @@ export type Observable<T> = { Defined at -[packages/core-api/src/types.ts:53](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L53). +[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L53). Referenced by: [sessionState\$](#sessionstate). ### Observer -This file contains non-react related core types used through Backstage. +This file contains non-react related core types used throughout Backstage. Observer interface for consuming an Observer, see TC39. @@ -94,7 +96,7 @@ export type Observer<T> = { Defined at -[packages/core-api/src/types.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L24). +[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L24). Referenced by: [Observable](#observable). @@ -110,7 +112,7 @@ export enum SessionState { Defined at -[packages/core-api/src/apis/definitions/auth.ts:182](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/auth.ts#L182). +[packages/core-api/src/apis/definitions/auth.ts:182](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/auth.ts#L182). Referenced by: [sessionState\$](#sessionstate). @@ -133,6 +135,6 @@ export type Subscription = { Defined at -[packages/core-api/src/types.ts:33](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L33). +[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L33). Referenced by: [Observable](#observable). diff --git a/docs/reference/utility-apis/SessionStateApi.md b/docs/reference/utility-apis/SessionStateApi.md index 81f25aa349..a8a4c3bc3d 100644 --- a/docs/reference/utility-apis/SessionStateApi.md +++ b/docs/reference/utility-apis/SessionStateApi.md @@ -1,7 +1,7 @@ # SessionStateApi The SessionStateApi type is defined at -[packages/core-api/src/apis/definitions/auth.ts:201](https://github.com/spotify/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L201). +[packages/core-api/src/apis/definitions/auth.ts:201](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L201). The following Utility APIs implement this type: @@ -56,7 +56,7 @@ export type Observable<T> = { Defined at -[packages/core-api/src/types.ts:53](https://github.com/spotify/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L53). +[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L53). Referenced by: [sessionState\$](#sessionstate). @@ -75,7 +75,7 @@ export type Observer<T> = { Defined at -[packages/core-api/src/types.ts:24](https://github.com/spotify/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L24). +[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L24). Referenced by: [Observable](#observable). @@ -91,7 +91,7 @@ export enum SessionState { Defined at -[packages/core-api/src/apis/definitions/auth.ts:192](https://github.com/spotify/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L192). +[packages/core-api/src/apis/definitions/auth.ts:192](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/apis/definitions/auth.ts#L192). Referenced by: [sessionState\$](#sessionstate). @@ -114,6 +114,6 @@ export type Subscription = { Defined at -[packages/core-api/src/types.ts:33](https://github.com/spotify/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L33). +[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/82d329555c16af46db9b4e5cd2f44a3cc006a52e/packages/core-api/src/types.ts#L33). Referenced by: [Observable](#observable). diff --git a/docs/reference/utility-apis/StorageApi.md b/docs/reference/utility-apis/StorageApi.md index e7d5131ff9..6c5595d3d8 100644 --- a/docs/reference/utility-apis/StorageApi.md +++ b/docs/reference/utility-apis/StorageApi.md @@ -1,7 +1,7 @@ # StorageApi The StorageApi type is defined at -[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/StorageApi.ts#L31). +[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/StorageApi.ts#L31). The following Utility API implements this type: [storageApiRef](./README.md#storage) @@ -79,13 +79,13 @@ export type Observable<T> = { Defined at -[packages/core-api/src/types.ts:53](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L53). +[packages/core-api/src/types.ts:53](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L53). Referenced by: [observe\$](#observe), [StorageApi](#storageapi). ### Observer -This file contains non-react related core types used through Backstage. +This file contains non-react related core types used throughout Backstage. Observer interface for consuming an Observer, see TC39. @@ -98,7 +98,7 @@ export type Observer<T> = { Defined at -[packages/core-api/src/types.ts:24](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L24). +[packages/core-api/src/types.ts:24](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L24). Referenced by: [Observable](#observable). @@ -144,7 +144,7 @@ export interface StorageApi { Defined at -[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/StorageApi.ts#L31). +[packages/core-api/src/apis/definitions/StorageApi.ts:31](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/StorageApi.ts#L31). Referenced by: [forBucket](#forbucket). @@ -158,7 +158,7 @@ export type StorageValueChange<T = any> = { Defined at -[packages/core-api/src/apis/definitions/StorageApi.ts:21](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/apis/definitions/StorageApi.ts#L21). +[packages/core-api/src/apis/definitions/StorageApi.ts:21](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/apis/definitions/StorageApi.ts#L21). Referenced by: [observe\$](#observe), [StorageApi](#storageapi). @@ -181,6 +181,6 @@ export type Subscription = { Defined at -[packages/core-api/src/types.ts:33](https://github.com/spotify/backstage/blob/0406ace29aba7332a98ff9ef9feedd65adc75223/packages/core-api/src/types.ts#L33). +[packages/core-api/src/types.ts:33](https://github.com/backstage/backstage/blob/ca535f2f66c3a4980c80f4b1a049dfd07569010e/packages/core-api/src/types.ts#L33). Referenced by: [Observable](#observable). diff --git a/docs/support/project-structure.md b/docs/support/project-structure.md index 277ca3929f..034fba4cb8 100644 --- a/docs/support/project-structure.md +++ b/docs/support/project-structure.md @@ -15,48 +15,48 @@ In the project root, there are a set of files and folders which are not part of the project as such, and may or may not be familiar to someone looking through the code. -- [`.changeset/`](https://github.com/spotify/backstage/tree/master/.changeset) - +- [`.changeset/`](https://github.com/backstage/backstage/tree/master/.changeset) - This folder contains files outlining which changes occurred in the project since the last release. These files are added manually, but managed by [changesets](https://github.com/atlassian/changesets) and will be removed at every new release. They are essentially building-blocks of a CHANGELOG. -- [`.github/`](https://github.com/spotify/backstage/tree/master/.github) - +- [`.github/`](https://github.com/backstage/backstage/tree/master/.github) - Standard GitHub folder. It contains - amongst other things - our workflow definitions and templates. Worth noting is the - [styles](https://github.com/spotify/backstage/tree/master/.github/styles) + [styles](https://github.com/backstage/backstage/tree/master/.github/styles) folder which is used for a markdown spellchecker. -- [`.yarn/`](https://github.com/spotify/backstage/tree/master/.yarn) - Backstage - ships with it's own `yarn` implementation. This allows us to have better - control over our `yarn.lock` file and hopefully avoid problems due to yarn - versioning differences. +- [`.yarn/`](https://github.com/backstage/backstage/tree/master/.yarn) - + Backstage ships with it's own `yarn` implementation. This allows us to have + better control over our `yarn.lock` file and hopefully avoid problems due to + yarn versioning differences. -- [`docker/`](https://github.com/spotify/backstage/tree/master/docker) - Files +- [`docker/`](https://github.com/backstage/backstage/tree/master/docker) - Files related to our root Dockerfile. We are planning to refactor this, so expect this folder to be moved in the future. -- [`contrib/`](https://github.com/spotify/backstage/tree/master/contrib) - +- [`contrib/`](https://github.com/backstage/backstage/tree/master/contrib) - Collection of examples or resources provided by the community. We really appreciate contributions in here and encourage them being kept up to date. -- [`docs/`](https://github.com/spotify/backstage/tree/master/docs) - This is - where we keep all of our documentation markdown files. These ends up on - http://backstage.io/docs. Just keep in mind that changes to - [this](https://github.com/spotify/backstage/blob/master/microsite/sidebars.json) - file also needs to be updated. +- [`docs/`](https://github.com/backstage/backstage/tree/master/docs) - This is + where we keep all of our documentation Markdown files. These ends up on + http://backstage.io/docs. Just keep in mind that changes to the + [`sidebars.json`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.json) + file may be needed as sections are added/removed. -- [`.editorconfig`](https://github.com/spotify/backstage/tree/master/.editorconfig) - +- [`.editorconfig`](https://github.com/backstage/backstage/tree/master/.editorconfig) - A configuration file used by most common code editors. -- [`.imgbotconfig`](https://github.com/spotify/backstage/tree/master/.imgbotconfig) - +- [`.imgbotconfig`](https://github.com/backstage/backstage/tree/master/.imgbotconfig) - Configuration for a [bot](https://imgbot.net/) ## Monorepo packages Every folder in both `packages/` and `plugins/` is within our monorepo setup, as defined in -[`package.json`](https://github.com/spotify/backstage/blob/master/package.json): +[`package.json`](https://github.com/backstage/backstage/blob/master/package.json): ```json "workspaces": { @@ -71,119 +71,115 @@ Let's look at them individually. ### `packages/` -These are all the packages that is we use within the project. -[Plugins](#plugins) are separated out into their own folder, see further down. +These are all the packages that we use within the project. [Plugins](#plugins) +are separated out into their own folder, see further down. -- [`app/`](https://github.com/spotify/backstage/tree/master/packages/app) - This - is our take on how an App could look like, bringing together a set of packages - and plugins into a working Backstage App. This is not a published package, and - the main goals is to provide a demo of what an App could look like, and also - enabling local development. +- [`app/`](https://github.com/backstage/backstage/tree/master/packages/app) - + This is our take on how an App could look like, bringing together a set of + packages and plugins into a working Backstage App. This is not a published + package, and the main goals are to provide a demo of what an App could look + like and to enable local development. -- [`backend/`](https://github.com/spotify/backstage/tree/master/packages/backend) - - Every standalone backstage project will have both an `app` _and_ a `backend` +- [`backend/`](https://github.com/backstage/backstage/tree/master/packages/backend) - + Every standalone Backstage project will have both an `app` _and_ a `backend` package. The `backend` uses plugins to construct a working backend that the frontend (`app`) can use. -- [`backend-common/`](https://github.com/spotify/backstage/tree/master/packages/backend-common) - +- [`backend-common/`](https://github.com/backstage/backstage/tree/master/packages/backend-common) - There are no "core" packages in the backend. Instead we have `backend-common` - which contains helper middleware´s and other utils. + which contains helper middleware and other utils. -- [`catalog-model/`](https://github.com/spotify/backstage/tree/master/packages/catalog-model) - - You can considers this to be a library for working with the catalog of sorts. +- [`catalog-model/`](https://github.com/backstage/backstage/tree/master/packages/catalog-model) - + You can consider this to be a library for working with the catalog of sorts. It contains the definition of an [Entity](https://backstage.io/docs/features/software-catalog/references#docsNav), - as well as validation an other logic related to it. This package can be used + as well as validation and other logic related to it. This package can be used in both the frontend and the backend. -- [`cli/`](https://github.com/spotify/backstage/tree/master/packages/cli) - One - of the biggest packages in our project, the `cli` is used to build, serve, +- [`cli/`](https://github.com/backstage/backstage/tree/master/packages/cli) - + One of the biggest packages in our project, the `cli` is used to build, serve, diff, create-plugins and more. In the early days of this project, we started - out with calling tools directly - such as `eslint` - through package.json. But - as it was tricky to have a good development experience around that when we + out with calling tools directly - such as `eslint` - through `package.json`. + But as it was tricky to have a good development experience around that when we change named tooling, we opted for wrapping those in our own cli. That way - everything looks the same in package.json. Much like + everything looks the same in `package.json`. Much like [react-scripts](https://github.com/facebook/create-react-app/tree/master/packages/react-scripts). -- [`cli-common/`](https://github.com/spotify/backstage/tree/master/packages/cli-common) - +- [`cli-common/`](https://github.com/backstage/backstage/tree/master/packages/cli-common) - This package mainly handles path resolving. It is a separate package to reduce - bugs in [cli](https://github.com/spotify/backstage/tree/master/packages/cli). - We also want as few dependencies as possible to reduce download time when - running the cli which is another reason this is a separate package. + bugs in + [cli](https://github.com/backstage/backstage/tree/master/packages/cli). We + also want as few dependencies as possible to reduce download time when running + the cli which is another reason this is a separate package. -* [`config/`](https://github.com/spotify/backstage/tree/master/packages/config) - +- [`config/`](https://github.com/backstage/backstage/tree/master/packages/config) - The way we read configuration data. This package can take a bunch of config objects and merge them together. - [app-config.yaml](https://github.com/spotify/backstage/blob/master/app-config.yaml) + [app-config.yaml](https://github.com/backstage/backstage/blob/master/app-config.yaml) is an example of an config object. -* [`config-loader/`](https://github.com/spotify/backstage/tree/master/packages/config-loader) - +- [`config-loader/`](https://github.com/backstage/backstage/tree/master/packages/config-loader) - This package is used to read config objects. It does not know how to merge, - this only reads files and passes them on to the config. As this part os only + but only reads files and passes them on to the config. As this part is only used by the backend, we chose to separate `config` and `config-loader` into two different packages. -- [`core/`](https://github.com/spotify/backstage/tree/master/packages/core) - +- [`core/`](https://github.com/backstage/backstage/tree/master/packages/core) - This package contains our visual React components, some of which you can find - [here](https://backstage.io/storybook/?path=/story/plugins-examples--plugin-with-data). + 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/spotify/backstage/tree/master/packages/core-api) - - This package contains apis and definitions of such. It is it's own 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 + detail that we try to hide from our users, and no one should have to depend on it directly. -* [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils) - +- [`test-utils/`](https://github.com/backstage/backstage/tree/master/packages/test-utils) - This package contains specific testing facilities used when testing `core-api`. -* [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core) - - This package contains more general purpose testing facilities for testing an +- [`test-utils-core/`](https://github.com/backstage/backstage/tree/master/packages/test-utils-core) - + This package contains more general purpose testing facilities for testing a Backstage App. -* [`create-app/`](https://github.com/spotify/backstage/tree/master/packages/create-app) - +- [`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 - [template](https://github.com/spotify/backstage/tree/master/packages/create-app/templates/default-app). + [template](https://github.com/backstage/backstage/tree/master/packages/create-app/templates/default-app). -- [`dev-utils/`](https://github.com/spotify/backstage/tree/master/packages/dev-utils) - +- [`dev-utils/`](https://github.com/backstage/backstage/tree/master/packages/dev-utils) - Helps you setup a plugin for isolated development so that it can be served separately. -* [`docgen/`](https://github.com/spotify/backstage/tree/master/packages/docgen) - +- [`docgen/`](https://github.com/backstage/backstage/tree/master/packages/docgen) - Uses the [Typescript Compiler API](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API) to read out definitions and generate documentation for it. -* [`e2e-test/`](https://github.com/spotify/backstage/tree/master/packages/e2e-test) - +- [`e2e-test/`](https://github.com/backstage/backstage/tree/master/packages/e2e-test) - Another CLI that can be run to try out what would happen if you built all the packages, publish them, created a new app, and the run it. CI uses this for e2e-tests. -* [`storybook/`](https://github.com/spotify/backstage/tree/master/packages/storybook) - +- [`storybook/`](https://github.com/backstage/backstage/tree/master/packages/storybook) - This folder contains only the storybook config. Stories are within the core package. The Backstage Storybook is found [here](https://backstage.io/storybook) -* [`techdocs-cli/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-cli) - - Used for verifying TechDocs locally. +- [`test-utils-core/`](https://github.com/backstage/backstage/tree/master/packages/test-utils-core) -* [`techdocs-container/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-container) - - Used by the `techdocs-cli` +- [`test-utils/`](https://github.com/backstage/backstage/tree/master/packages/test-utils) -* [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core) - -* [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils) - -* [`theme/`](https://github.com/spotify/backstage/tree/master/packages/theme) - +- [`theme/`](https://github.com/backstage/backstage/tree/master/packages/theme) - Holds the Backstage Theme. ### `plugins/` -Most of the functionality of an Backstage App comes from plugins. Even core +Most of the functionality of a Backstage App comes from plugins. Even core features can be plugins, take the -[catalog](https://github.com/spotify/backstage/tree/master/plugins/catalog) as +[catalog](https://github.com/backstage/backstage/tree/master/plugins/catalog) as an example. We can categorize plugins into three different types; **Frontend**, **Backend** @@ -195,18 +191,18 @@ reason is for clear separation of concerns. Take a look at our [Plugin Gallery](https://backstage.io/plugins) or browse through the -[`plugins/`](https://github.com/spotify/backstage/tree/master/plugins) folder. +[`plugins/`](https://github.com/backstage/backstage/tree/master/plugins) folder. ## Packages outside of the monorepo -For convenience we include packages in our project that is not part of our +For convenience we include packages in our project that are not part of our monorepo setup. -- [`microsite/`](https://github.com/spotify/backstage/blob/master/microsite) - +- [`microsite/`](https://github.com/backstage/backstage/blob/master/microsite) - This folder contains the source code for backstage.io. It is built with [Docusaurus](https://docusaurus.io/). This folder is not part of the monorepo due to dependency reasons. Look at the - [README](https://github.com/spotify/backstage/blob/master/microsite/README.md) + [README](https://github.com/backstage/backstage/blob/master/microsite/README.md) for instructions on how to run it locally. ## Root files specifically used by the `app` @@ -215,25 +211,22 @@ These files are kept in the root of the project mostly by historical reasons. Some of these files may be subject to be moved out of the root sometime in the future. -- [`.npmrc`](https://github.com/spotify/backstage/tree/master/.npmrc) - It's +- [`.npmrc`](https://github.com/backstage/backstage/tree/master/.npmrc) - It's common for companies to have their own npm registry, this files makes sure that this folder use the public registry. -- [`.vale.ini`](https://github.com/spotify/backstage/tree/master/.vale.ini) - - [Spell checker](https://github.com/errata-ai/vale) for markdown files +- [`.vale.ini`](https://github.com/backstage/backstage/tree/master/.vale.ini) - + [Spell checker](https://github.com/errata-ai/vale) for Markdown files. -- [`.yarnrc`](https://github.com/spotify/backstage/tree/master/.yarnrc) - - Enforces "our" version of yarn. +- [`.yarnrc`](https://github.com/backstage/backstage/tree/master/.yarnrc) - + Enforces "our" version of Yarn. -- [`app-config.yaml`](https://github.com/spotify/backstage/tree/master/app-config.yaml) - - Configuration for the app, both frontend and backend +- [`app-config.yaml`](https://github.com/backstage/backstage/tree/master/app-config.yaml) - + Configuration for the app, both frontend and backend. -- [`app-config.development.yaml`](https://github.com/spotify/backstage/tree/master/app-config.development.yaml) - - Used for overriding configuration when developing locally. - -- [`catalog-info.yaml`](https://github.com/spotify/backstage/tree/master/catalog-info.yaml) - +- [`catalog-info.yaml`](https://github.com/backstage/backstage/tree/master/catalog-info.yaml) - Description of Backstage in the Backstage Entity format. -- [`lerna.json`](https://github.com/spotify/backstage/tree/master/lerna.json) - - [lerna](https://github.com/lerna/lerna) monorepo config. We are using +- [`lerna.json`](https://github.com/backstage/backstage/tree/master/lerna.json) - + [Lerna](https://github.com/lerna/lerna) monorepo config. We are using `yarn workspaces`, so this will only be used for executing scripts. diff --git a/docs/support/support.md b/docs/support/support.md index 12bc7cfaf9..49075366af 100644 --- a/docs/support/support.md +++ b/docs/support/support.md @@ -5,15 +5,16 @@ description: Support and Community Details and Links --- - [Discord chatroom](https://discord.gg/MUpMjP2) - Get support or discuss the - project -- [Good First Issues](https://github.com/spotify/backstage/contribute) - Start - here if you want to contribute -- [RFCs](https://github.com/spotify/backstage/labels/rfc) - Help shape the - technical direction -- [FAQ](../FAQ.md) - Frequently Asked Questions -- [Code of Conduct](../../CODE_OF_CONDUCT.md) - This is how we roll -- [Blog](https://backstage.io/blog/) - Announcements and updates + project. +- [Good First Issues](https://github.com/backstage/backstage/contribute) - Start + here if you want to contribute. +- [RFCs](https://github.com/backstage/backstage/labels/rfc) - Help shape the + technical direction by reviewing _Request for Comments_ issues. +- [FAQ](../FAQ.md) - Frequently Asked Questions. +- [Code of Conduct](https://github.com/backstage/backstage/blob/master/CODE_OF_CONDUCT.md) - + This is how we roll. +- [Blog](https://backstage.io/blog/) - Announcements and updates. - [Newsletter](https://mailchi.mp/spotify/backstage-community) - Subscribe to - our email newsletter + our email newsletter. - Give us a star ⭐️ - If you are using Backstage or think it is an interesting - project, we would love a star ❤️ + project, we would love a star! ❤️ diff --git a/docs/tutorials/journey.md b/docs/tutorials/journey.md index 908d7fc61b..664d4b77d3 100644 --- a/docs/tutorials/journey.md +++ b/docs/tutorials/journey.md @@ -179,7 +179,7 @@ const onSave = async () => { ``` Now it's much simpler for users to change the theme tune, as they no longer need -to go look up a track ID and edit a yaml file. Instead, they can now stay inside +to go look up a track ID and edit a YAML file. Instead, they can now stay inside Backstage and search for the track and request the change from there. In addition, the requested change can be reviewed by the regular process of each organization. @@ -239,12 +239,12 @@ hits merge. # 8. Attack of the Clones Sam just released v1.8.4 of the plugin, and at this point it's so popular that a -couple of other plugins has started depending on the `sam.wise/spotify-track-id` -annotation. One such plugin being the `spotify-album-art` plugin that can -display the album art of the theme tune as the background of the entity header. -Sam thinks it's all pretty cool, but doesn't like that the annotation that was -once an internal concern of the plugin is now becoming a standard in the -community. +couple of other plugins have started depending on the +`sam.wise/spotify-track-id` annotation. One such plugin being the +`spotify-album-art` plugin that can display the album art of the theme tune as +the background of the entity header. Sam thinks it's all pretty cool, but +doesn't like that the annotation that was once an internal concern of the plugin +is now becoming a standard in the community. In order to standardize the annotation in Backstage, Sam submits a Pull Request to the Backstage Core repo. The request suggests a new well-known metadata @@ -264,14 +264,9 @@ release of Sam's plugin specifies a dependency on Backstage with a minimum version set to the same release as the one were the annotation was added to the core schema. -
- - # 9. Revenge of the Sam Sam, now in full control of all theme tunes in Backstage, releases v2.0.1, which switches all tracks to 4uLU6hMCjMI75M1A2tKUQC. Sam wanted to do something more nefarious, but since Backstage sandboxes sensitive actions and is mostly read-only with strict CSP, Sam's hands were tied. - -
diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md index 8f6b35617b..1dcca9d7e0 100644 --- a/docs/tutorials/quickstart-app-auth.md +++ b/docs/tutorials/quickstart-app-auth.md @@ -7,11 +7,11 @@ title: Monorepo App Setup With Authentication
-> This document takes you through setting up a backstage app that runs in your +> This document takes you through setting up a Backstage app that runs in your > own environment. It starts with a skeleton install and verifying of the > monorepo's functionality. Next, GitHub authentication is added and tested. > -> This document assumes you have NodeJS 12 active along with Yarn and Python. +> This document assumes you have Node.js 12 active along with Yarn and Python. > Please note, that at the time of this writing, the current version is > 0.1.1-alpha.21. This guide can still be used with future versions, just, > verify as you go. If you run into issues, you can compare your setup with mine diff --git a/docs/tutorials/quickstart-app-plugin.md b/docs/tutorials/quickstart-app-plugin.md index 9f571b0c9a..216ff9659f 100644 --- a/docs/tutorials/quickstart-app-plugin.md +++ b/docs/tutorials/quickstart-app-plugin.md @@ -20,7 +20,7 @@ title: Adding Custom Plugin to Existing Monorepo App > functionality, extend the Sidebar to make our life easy. Finally, we add > custom code to display GitHub repository information. > -> This document assumes you have NodeJS 12 active along with Yarn and Python. +> This document assumes you have Node.js 12 active along with Yarn and Python. > Please note, that at the time of this writing, the current version is > 0.1.1-alpha.21. This guide can still be used with future versions, just, > verify as you go. If you run into issues, you can compare your setup with mine @@ -120,10 +120,10 @@ If everything is saved, you should see your name, id, and email on the github-playground page. Our data accessed is synchronous. So we just grab and go. -https://github.com/spotify/backstage/tree/master/contrib +https://github.com/backstage/backstage/tree/master/contrib 6. Here is the entire file for reference - [ExampleComponent.tsx](https://github.com/spotify/backstage/tree/master/contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md) + [ExampleComponent.tsx](https://github.com/backstage/backstage/tree/master/contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md) # The Wipe @@ -161,7 +161,7 @@ export default ExampleFetchComponent; # The Graph Model -GitHub has a graphql API available for interacting. Let's start by adding our +GitHub has a GraphQL API available for interacting. Let's start by adding our basic repository query 1. Add the query const statement outside ExampleFetchComponent @@ -302,7 +302,7 @@ return ( 8. After saving that, and given we don't have any errors, you should see a table with basic information on your repositories. 9. Here is the entire file for reference - [ExampleFetchComponent.tsx](https://github.com/spotify/backstage/tree/master/contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md) + [ExampleFetchComponent.tsx](https://github.com/backstage/backstage/tree/master/contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md) 10. We finished! You should see your own GitHub repository's information displayed in a basic table. If you run into issues, you can compare the repo that backs this document, diff --git a/docs/verify-links.js b/docs/verify-links.js deleted file mode 100755 index 9bf8a67ad8..0000000000 --- a/docs/verify-links.js +++ /dev/null @@ -1,131 +0,0 @@ -#!/usr/bin/env node -/* - * Copyright 2020 Spotify AB - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -const { resolve: resolvePath, dirname } = require('path'); -const fs = require('fs-extra'); -const recursive = require('recursive-readdir'); - -const projectRoot = resolvePath(__dirname, '..'); - -async function verifyUrl(basePath, url) { - // Avoid having absolute URL links within docs/, so that links work on the site - if ( - url.match( - /https:\/\/github.com\/spotify\/backstage\/(tree|blob)\/master\/docs\//, - ) && - basePath.match(/^(?:docs|microsite)\//) - ) { - return { url, basePath, problem: 'absolute' }; - } - - url = url.replace(/#.*$/, ''); - url = url.replace( - /https:\/\/github.com\/spotify\/backstage\/(tree|blob)\/master/, - '', - ); - if (!url) { - return; - } - - // Only verify existence of local files for now, so skip anything with a schema - if (url.match(/[a-z]+:/)) { - return; - } - - let path = ''; - - if (url.startsWith('/')) { - if (url.startsWith('/docs/') && basePath.match(/^(?:docs|microsite)\//)) { - return { url, basePath, problem: 'not-relative' }; - } - - const staticPath = resolvePath(projectRoot, 'microsite/static', `.${url}`); - if (await fs.pathExists(staticPath)) { - return; - } - - path = resolvePath(projectRoot, `.${url}`); - } else { - path = resolvePath(dirname(resolvePath(projectRoot, basePath)), url); - } - - const exists = await fs.pathExists(path); - if (!exists) { - return { url, basePath, problem: 'missing' }; - } - - return; -} - -async function verifyFile(filePath) { - const content = await fs.readFile(filePath, 'utf8'); - const mdLinks = content.match(/\[.+?\]\(.+?\)/g) || []; - const badUrls = []; - - for (const mdLink of mdLinks) { - const url = mdLink.match(/\[.+\]\((.+)\)/)[1].trim(); - const badUrl = await verifyUrl(filePath, url); - if (badUrl) { - badUrls.push(badUrl); - } - } - - return badUrls; -} - -async function main() { - process.chdir(projectRoot); - - const files = await recursive('.', [ - 'node_modules', - 'dist', - 'bin', - 'microsite', - ]); - const mdFiles = files.filter(f => f.endsWith('.md')); - const badUrls = []; - - for (const mdFile of mdFiles) { - const badFileUrls = await verifyFile(mdFile); - badUrls.push(...badFileUrls); - } - - if (badUrls.length) { - console.log(`Found ${badUrls.length} bad links within repo`); - for (const { url, basePath, problem } of badUrls) { - if (problem === 'missing') { - console.error( - `Unable to reach ${url} from root or microsite/static/, linked from ${basePath}`, - ); - } else if (problem === 'not-relative') { - console.error('Links to /docs/ must be relative'); - console.error(` From: ${basePath}`); - console.error(` To: ${url}`); - } else if (problem === 'absolute') { - console.error(`Link to docs/ should be replaced by a relative URL`); - console.error(` From: ${basePath}`); - console.error(` To: ${url}`); - } - } - process.exit(1); - } -} - -main().catch(error => { - console.error(error.stack); - process.exit(1); -}); diff --git a/lerna.json b/lerna.json index f804c800de..dd2dd884eb 100644 --- a/lerna.json +++ b/lerna.json @@ -2,5 +2,5 @@ "packages": ["packages/*", "plugins/*"], "npmClient": "yarn", "useWorkspaces": true, - "version": "0.1.1-alpha.25" + "version": "0.1.1" } diff --git a/microsite/blog/2020-03-16-announcing-backstage.md b/microsite/blog/2020-03-16-announcing-backstage.md index 3911debf08..5824b76a57 100644 --- a/microsite/blog/2020-03-16-announcing-backstage.md +++ b/microsite/blog/2020-03-16-announcing-backstage.md @@ -41,4 +41,4 @@ We are envisioning three phases of the project and we have already begun work on - **Phase 3:** Ecosystem (later) - Everyone's infrastructure stack is different. By fostering a vibrant community of contributors we hope to provide an ecosystem of Open Source plugins/integrations that allows you to pick the tools that match your stack. -Our vision for Backstage is for it to become the trusted standard toolbox (read: UI layer) for the open source infrastructure landscape. Think of it like Kubernetes for developer experience. We realize this is an ambitious goal. We can’t do it alone. If this sounds interesting or you'd like to help us shape our product vision, we'd love to talk. You can email me directly: [alund@spotify.com](mailto:alund@spotify.com). +Our vision for Backstage is for it to become the trusted standard toolbox (read: UI layer) for the open source infrastructure landscape. Think of it like Kubernetes for developer experience. We realize this is an ambitious goal. We can’t do it alone. If this sounds interesting or you'd like to help us shape our product vision, we'd love to talk. You can email us directly: [backstage-interest@spotify.com](mailto:backstage-interest@spotify.com). diff --git a/microsite/blog/2020-03-18-what-is-backstage.md b/microsite/blog/2020-03-18-what-is-backstage.md index 8b0a0fcbe6..f4f62e2cf7 100644 --- a/microsite/blog/2020-03-18-what-is-backstage.md +++ b/microsite/blog/2020-03-18-what-is-backstage.md @@ -81,8 +81,8 @@ Similar to how Backstage ties together all of Spotify’s infrastructure, our am ## What’s next? -We are envisioning [three phases](https://github.com/spotify/backstage/milestones) of the project (so far), and we have already begun work on various aspects of these phases. The best way to track the work and see where you can jump in and help out is: +We are envisioning [three phases](https://github.com/backstage/backstage/milestones) of the project (so far), and we have already begun work on various aspects of these phases. The best way to track the work and see where you can jump in and help out is: -https://github.com/spotify/backstage/milestones +https://github.com/backstage/backstage/milestones -Want to discuss the project or need support? Join us on [Discord](https://discord.gg/MUpMjP2) or reach out on [alund@spotify.com](mailto:alund@spotify.com). +Want to discuss the project or need support? Join us on [Discord](https://discord.gg/MUpMjP2) or reach out on [backstage-interest@spotify.com](mailto:backstage-interest@spotify.com). diff --git a/microsite/blog/2020-04-06-lighthouse-plugin.md b/microsite/blog/2020-04-06-lighthouse-plugin.md index 2d5c7b96b7..b8fd68e783 100644 --- a/microsite/blog/2020-04-06-lighthouse-plugin.md +++ b/microsite/blog/2020-04-06-lighthouse-plugin.md @@ -33,7 +33,7 @@ Trigger an audit directly from Backstage, or trigger audits programmatically wit ## Using Lighthouse in Backstage -To learn how you can enable Lighthouse auditing within Backstage, head over to the [README](https://github.com/spotify/backstage/tree/master/plugins/lighthouse) for the plugin to get started. +To learn how you can enable Lighthouse auditing within Backstage, head over to the [README](https://github.com/backstage/backstage/tree/master/plugins/lighthouse) for the plugin to get started. ## A personal note diff --git a/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md b/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md index dff567eaf3..85f40dd9ea 100644 --- a/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md +++ b/microsite/blog/2020-04-30-how-to-quickly-set-up-backstage.md @@ -132,4 +132,4 @@ If you are developing a plugin that might be useful for others, consider releasi ## Ready to get started? -Head over to GitHub and check out the [project](https://github.com/spotify/backstage) or download our [CLI](https://www.npmjs.com/package/@backstage/cli). If you have more questions, join us on [Discord](https://discord.gg/MUpMjP2) or [create an issue](https://github.com/spotify/backstage/issues/new/choose). +Head over to GitHub and check out the [project](https://github.com/backstage/backstage) or download our [CLI](https://www.npmjs.com/package/@backstage/cli). If you have more questions, join us on [Discord](https://discord.gg/MUpMjP2) or [create an issue](https://github.com/backstage/backstage/issues/new/choose). diff --git a/microsite/blog/2020-05-14-tech-radar-plugin.md b/microsite/blog/2020-05-14-tech-radar-plugin.md index d78d5d67fa..80c1eb8b5a 100644 --- a/microsite/blog/2020-05-14-tech-radar-plugin.md +++ b/microsite/blog/2020-05-14-tech-radar-plugin.md @@ -34,11 +34,11 @@ To learn about how you can bring the Tech Radar to your Backstage installation, I want to thank both the Backstage team and Spotify. Firstly, I’ve been working with our internal version of Backstage for over a year, and the developer experience since open sourcing has been even more of a joy to work with. Secondly, the 10% hack time that Spotify generously provides to all engineers enabled me to open source the Tech Radar plugin. -Since open sourcing it, the community has shown great interest in yet another powerful use case of Backstage. There was also an enthusiastic open source contributor who volunteered to migrate the plugin to TypeScript and React Hooks [in just 29 minutes](https://github.com/spotify/backstage/issues/661) of opening the issue! +Since open sourcing it, the community has shown great interest in yet another powerful use case of Backstage. There was also an enthusiastic open source contributor who volunteered to migrate the plugin to TypeScript and React Hooks [in just 29 minutes](https://github.com/backstage/backstage/issues/661) of opening the issue! I can’t wait to see how others benefit from the Tech Radar in their organizations! [lighthouse website audits]: https://backstage.io/blog/2020/04/06/lighthouse-plugin -[tech radar plugin]: https://github.com/spotify/backstage/tree/master/plugins/tech-radar +[tech radar plugin]: https://github.com/backstage/backstage/tree/master/plugins/tech-radar [thoughtworks]: https://www.thoughtworks.com/radar [zalando]: https://opensource.zalando.com/tech-radar/ diff --git a/microsite/blog/2020-05-22-phase-2-service-catalog.md b/microsite/blog/2020-05-22-phase-2-service-catalog.md index 682965d2dd..103750dcc6 100644 --- a/microsite/blog/2020-05-22-phase-2-service-catalog.md +++ b/microsite/blog/2020-05-22-phase-2-service-catalog.md @@ -7,7 +7,7 @@ authorImageURL: https://pbs.twimg.com/profile_images/121166861/6919c047c0d0edaac **TL;DR** Thanks to the help from the Backstage community, we’ve made excellent progress and are now moving into Phase 2 of Backstage — building out a Service Catalog and the surrounding systems that will help unify the tools you use to manage your software. -We released the open source version of Backstage a little less than two months ago, and have been thrilled to see so many people jumping in and contributing to the project in its early stages. We’re excited to see what the community can build together as we progress through [each phase of Backstage](https://github.com/spotify/backstage#project-roadmap). +We released the open source version of Backstage a little less than two months ago, and have been thrilled to see so many people jumping in and contributing to the project in its early stages. We’re excited to see what the community can build together as we progress through [each phase of Backstage](https://github.com/backstage/backstage#project-roadmap). ![img](assets/20-05-20/Service_Catalog_MVP.png) @@ -15,7 +15,7 @@ We released the open source version of Backstage a little less than two months a ## Progress so far -Phase 1 was all about building an extensible frontend platform, enabling teams to start creating a single, consistent UI layer for your internal infrastructure and tools in the form of [plugins](https://github.com/spotify/backstage/labels/plugin). In fact, thanks to our amazing (30+) [contributors](https://github.com/spotify/backstage/graphs/contributors), we were able to complete most of Phase 1 earlier than expected. 🎉 +Phase 1 was all about building an extensible frontend platform, enabling teams to start creating a single, consistent UI layer for your internal infrastructure and tools in the form of [plugins](https://github.com/backstage/backstage/labels/plugin). In fact, thanks to our amazing (30+) [contributors](https://github.com/backstage/backstage/graphs/contributors), we were able to complete most of Phase 1 earlier than expected. 🎉 Today, we are happy to announce that we are shifting our focus to Phase 2! @@ -27,7 +27,7 @@ Quote from [Platform Nuts & Bolts: Extendable Data Models](https://www.kislayver Entities, or what we refer to as “components” in Backstage, represent all software, including services, websites, libraries, data pipelines, and so forth. The focus of Phase 2 will be on adding an entity model in Backstage that makes it easy for engineers to create and manage the software components they own. -With the ability to create a plethora of components in Backstage, how does one keep track of all the software in the ecosystem? Therein lies the highlight feature of Phase 2: the [Service Catalog](https://github.com/spotify/backstage/milestone/4). The service catalog — or software catalog — is a centralized system that keeps track of ownership and metadata about all software in your ecosystem. The catalog is built around the concept of [metadata yaml files](/docs/architecture-decisions/adr002-default-catalog-file-format.md) stored together with the code, which are then harvested and visualized in Backstage. +With the ability to create a plethora of components in Backstage, how does one keep track of all the software in the ecosystem? Therein lies the highlight feature of Phase 2: the [Service Catalog](https://github.com/backstage/backstage/milestone/4). The service catalog — or software catalog — is a centralized system that keeps track of ownership and metadata about all software in your ecosystem. The catalog is built around the concept of [metadata yaml files](/docs/architecture-decisions/adrs-adr002) stored together with the code, which are then harvested and visualized in Backstage. ![img](assets/20-05-20/Service_Catalog_MVP.png) @@ -39,13 +39,13 @@ On top of that, we have found that the service catalog is a great way to organis ![img](assets/20-05-20/tabs.png) -More concretely, having this structure in place will allow plugins such as [CircleCI](https://github.com/spotify/backstage/tree/master/plugins/circleci) to show only the builds for the specific service you are viewing, or a [Spinnaker](https://github.com/spotify/backstage/issues/631) plugin to show running deployments, or an Open API plugin to [show documentation](https://github.com/spotify/backstage/issues/627) for endpoints exposed by the service, or the [Lighthouse](https://github.com/spotify/backstage/tree/master/plugins/lighthouse) plugin to show audit reports for your website. You get the point. +More concretely, having this structure in place will allow plugins such as [CircleCI](https://github.com/backstage/backstage/tree/master/plugins/circleci) to show only the builds for the specific service you are viewing, or a [Spinnaker](https://github.com/backstage/backstage/issues/631) plugin to show running deployments, or an Open API plugin to [show documentation](https://github.com/backstage/backstage/issues/627) for endpoints exposed by the service, or the [Lighthouse](https://github.com/backstage/backstage/tree/master/plugins/lighthouse) plugin to show audit reports for your website. You get the point. ## Timeline Our estimated timeline has us delivering these pieces in increments leading up to June 22. But with the support of the community we wouldn’t be surprised if things land earlier than that. 🙏 -If you are interested in joining us, check out our [Milestones](https://github.com/spotify/backstage/milestones) and connected Issues. +If you are interested in joining us, check out our [Milestones](https://github.com/backstage/backstage/milestones) and connected Issues. ## Long-term vision diff --git a/microsite/blog/2020-06-22-backstage-service-catalog-alpha.md b/microsite/blog/2020-06-22-backstage-service-catalog-alpha.md index 0928b8769b..e50d7a6d47 100644 --- a/microsite/blog/2020-06-22-backstage-service-catalog-alpha.md +++ b/microsite/blog/2020-06-22-backstage-service-catalog-alpha.md @@ -24,7 +24,7 @@ With these insights we decided to re-focus our efforts towards the most requeste ## What is the service catalog? -The Backstage Service 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](/docs/architecture-decisions/adr002-default-catalog-file-format.md#format) stored together with the code, which are then harvested and visualized in Backstage. +The Backstage Service 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](/docs/architecture-decisions/adrs-adr002) stored together with the code, which are then harvested and visualized in Backstage. This was our pitch for the virtues of a service catalog when we first [announced](https://backstage.io/blog/2020/05/22/phase-2-service-catalog) it as part of Phase 2: @@ -40,7 +40,7 @@ You’ll be able to see many of these virtues in action with this alpha release Alpha is our shorthand for "we don’t yet think Backstage is ready for production, but we’d love for you to test it and provide us with feedback". However, you should be able to try out the functionality of the service catalog: -1. Register software components ([examples](https://github.com/spotify/backstage/tree/master/packages/catalog-model/examples)) +1. Register software components ([examples](https://github.com/backstage/backstage/tree/master/packages/catalog-model/examples)) 2. See all components represented in the catalog 3. Search across all components 4. Get an overview of the metadata of the components @@ -49,6 +49,6 @@ Alpha is our shorthand for "we don’t yet think Backstage is ready for producti As with most alpha releases, you should expect things to change quite a lot until we reach the beta stage (we’re targeting the end of summer). There are obviously many things missing as well, but we wanted to start collecting feedback early and make it easier to see the end-to-end flow. -If you have feedback or questions, please open a [GitHub issue](https://github.com/spotify/backstage/issues), ping us on [Discord chat](https://discord.gg/EBHEGzX) or send me an email at [alund@spotify.com](mailto:alund@spotify.com) 🙏 +If you have feedback or questions, please open a [GitHub issue](https://github.com/backstage/backstage/issues), ping us on [Discord chat](https://discord.gg/EBHEGzX) or send us an email at [backstage-interest@spotify.com](mailto:backstage-interest@spotify.com) 🙏 To get regular product updates and news about the Backstage community, sign up for the [Backstage newsletter](https://mailchi.mp/spotify/backstage-community). diff --git a/microsite/blog/2020-07-01-how-to-enable-authentication-in-backstage-using-passport.md b/microsite/blog/2020-07-01-how-to-enable-authentication-in-backstage-using-passport.md index ccdd8b34c6..9d41a21d05 100644 --- a/microsite/blog/2020-07-01-how-to-enable-authentication-in-backstage-using-passport.md +++ b/microsite/blog/2020-07-01-how-to-enable-authentication-in-backstage-using-passport.md @@ -21,7 +21,7 @@ Passport has allowed us to leverage an existing open-source authentication frame ![auth-landing-page](assets/20-07-01/auth-sidebar.png) -First, check out the provided Google and GitHub implementations! [Spin up a local copy of Backstage](https://backstage.io/blog/2020/04/30/how-to-quickly-set-up-backstage) along with our example-backend. You can find more documentation on setting up the example backend [here](https://github.com/spotify/backstage/tree/master/packages/backend), but be sure to include the relevant client IDs and secrets when running `yarn start`: +First, check out the provided Google and GitHub implementations! [Spin up a local copy of Backstage](https://backstage.io/blog/2020/04/30/how-to-quickly-set-up-backstage) along with our example-backend. You can find more documentation on setting up the example backend [here](https://github.com/backstage/backstage/tree/master/packages/backend), but be sure to include the relevant client IDs and secrets when running `yarn start`: ``` AUTH_GOOGLE_CLIENT_ID=x AUTH_GOOGLE_CLIENT_SECRET=x AUTH_GITHUB_CLIENT_ID=x AUTH_GITHUB_CLIENT_SECRET=x SENTRY_TOKEN=x LOG_LEVEL=debug yarn start @@ -39,8 +39,8 @@ Getting started is really straightforward, and can be broadly broken down into f 4. Add the provider to the backend. 5. Add a frontend Auth Utility API. -For full details, take a look at our [“Adding authentication providers” documentation](/docs/auth/add-auth-provider.md) and at the [excellent documentation](http://www.passportjs.org/docs/) provided by Passport. +For full details, take a look at our [“Adding authentication providers” documentation](/docs/auth/add-auth-provider) and at the [excellent documentation](http://www.passportjs.org/docs/) provided by Passport. ## Interested in contributing to the next steps for authentication? -We’ve already seen both GitLab and Okta contributions from the community — and we’re thinking about a few more providers we’d like to add to Backstage, too. You can find those, and other authentication-related issues, in our repository by filtering with the [auth label](https://github.com/spotify/backstage/issues?q=is%3Aissue+is%3Aopen+label%3Aauth). +We’ve already seen both GitLab and Okta contributions from the community — and we’re thinking about a few more providers we’d like to add to Backstage, too. You can find those, and other authentication-related issues, in our repository by filtering with the [auth label](https://github.com/backstage/backstage/issues?q=is%3Aissue+is%3Aopen+label%3Aauth). diff --git a/microsite/blog/2020-08-05-announcing-backstage-software-templates.md b/microsite/blog/2020-08-05-announcing-backstage-software-templates.md index 81d495e1c3..bd6ae8eeeb 100644 --- a/microsite/blog/2020-08-05-announcing-backstage-software-templates.md +++ b/microsite/blog/2020-08-05-announcing-backstage-software-templates.md @@ -73,6 +73,6 @@ Backstage ships with four example templates, but since these are likely not the We have learned that one of the keys to getting these standards adopted is to keep an open process. Templates are code. By making it clear to your engineers that you are open to pull requests, and that teams with different needs can add their own templates, you are on the path of striking a good balance between autonomy and standardization. -If you have feedback or questions, please open a [GitHub issue](https://github.com/spotify/backstage/issues), ping us on [Discord chat](https://discord.gg/EBHEGzX) or send me an email at [alund@spotify.com](mailto:alund@spotify.com) 🙏 +If you have feedback or questions, please open a [GitHub issue](https://github.com/backstage/backstage/issues), ping us on [Discord chat](https://discord.gg/EBHEGzX) or send us an email at [backstage-interest@spotify.com](mailto:backstage-interest@spotify.com) 🙏 To get regular product updates and news about the Backstage community, sign up for the [Backstage newsletter](https://mailchi.mp/spotify/backstage-community). diff --git a/microsite/blog/2020-09-08-announcing-tech-docs.md b/microsite/blog/2020-09-08-announcing-tech-docs.md index 48b6eeb7cc..ceab17d7be 100644 --- a/microsite/blog/2020-09-08-announcing-tech-docs.md +++ b/microsite/blog/2020-09-08-announcing-tech-docs.md @@ -21,11 +21,11 @@ But this is just one way to do it. Today we’re most excited for what the open ## Okay, let’s start collaborating -If you go to [GitHub](https://github.com/spotify/backstage/tree/master/plugins) now, you’ll find everything you need to start collaborating with us to build out the docs-like-code Backstage plugin — we’ll call it TechDocs in the open as well. +If you go to [GitHub](https://github.com/backstage/backstage/tree/master/plugins) now, you’ll find everything you need to start collaborating with us to build out the docs-like-code Backstage plugin — we’ll call it TechDocs in the open as well. -You’ll find the code in [techdocs](https://github.com/spotify/backstage/tree/master/plugins/techdocs) (frontend) and [techdocs-backend](https://github.com/spotify/backstage/tree/master/plugins/techdocs-backend). (There are also two separate packages [techdocs-cli](https://github.com/spotify/backstage/tree/master/packages/techdocs-cli) and [techdocs-container](https://github.com/spotify/backstage/tree/master/packages/techdocs-container).) +You’ll find the code in [techdocs](https://github.com/backstage/backstage/tree/master/plugins/techdocs) (frontend) and [techdocs-backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend). (There are also two separate packages [techdocs-cli](https://github.com/backstage/techdocs-cli) and [techdocs-container](https://github.com/backstage/techdocs-container).) -You’ll find issues to work on in the [issues queue](https://github.com/spotify/backstage/issues?q=is%3Aissue+is%3Aopen+label%3A%22docs-like-code%22+label%3A%22help+wanted%22), typically starting with TechDocs: and labeled with docs-like-code, some labeled good first issue. Feel free to add your own issues, of course. +You’ll find issues to work on in the [issues queue](https://github.com/backstage/backstage/issues?q=is%3Aissue+is%3Aopen+label%3A%22docs-like-code%22+label%3A%22help+wanted%22), typically starting with TechDocs: and labeled with docs-like-code, some labeled good first issue. Feel free to add your own issues, of course. ![available-templates](assets/announcing-techdocs/github-issues.png) diff --git a/microsite/blog/2020-09-23-backstage-cncf-sandbox.md b/microsite/blog/2020-09-23-backstage-cncf-sandbox.md index bcfd7c6245..8fc459cb62 100644 --- a/microsite/blog/2020-09-23-backstage-cncf-sandbox.md +++ b/microsite/blog/2020-09-23-backstage-cncf-sandbox.md @@ -14,8 +14,8 @@ Backstage garnered quite a bit of interest from developers and organizations whe Backstage’s ability to simplify tooling and standardize engineering practices has attracted interest from other major tech companies, as well as airlines, auto manufacturers, investment firms, and global retailers. We know that Backstage solves a problem — infrastructure complexity — that’s common to a lot of large and growing companies today. But different companies work differently, use particular toolsets, and have unique use cases. By making Backstage open source, we can build it with people working inside a variety of engineering organizations all over the world. It makes for a better product that serves a wider group of users (beyond that of Spotify’s) and their needs. -The Backstage community is healthy and growing quickly. Over [130 people](https://github.com/spotify/backstage/graphs/contributors) have contributed to the project, and roughly 40% of pull requests are now coming from external, non-Spotify, contributors. With companies now deciding to [adopt Backstage](https://github.com/spotify/backstage/blob/master/ADOPTERS.md) we are also seeing a shift in the kinds of contributions we are getting from the community. It is truly amazing to see contributions to core parts of the platform as well as significant functionality additions through working [plugins](https://backstage.io/plugins). +The Backstage community is healthy and growing quickly. Over [130 people](https://github.com/backstage/backstage/graphs/contributors) have contributed to the project, and roughly 40% of pull requests are now coming from external, non-Spotify, contributors. With companies now deciding to [adopt Backstage](https://github.com/backstage/backstage/blob/master/ADOPTERS.md) we are also seeing a shift in the kinds of contributions we are getting from the community. It is truly amazing to see contributions to core parts of the platform as well as significant functionality additions through working [plugins](https://backstage.io/plugins). We’re excited to embark on this journey with the CNCF community. There’s so much great tech being built here, and it’s about time we share it to build even greater products, together. Entering into the CNCF Sandbox is just the first step. We are committed to working with the community to bring Backstage through the Incubation step, and finally all the way to becoming a Graduated, top-level project. -Thanks to everyone for your support so far. We hope you [join us](https://mailchi.mp/spotify/backstage-community) in this next chapter of Backstage's journey. If you have questions or feedback, feel free to [email](mailto:alund@spotify.com) me directly. +Thanks to everyone for your support so far. We hope you [join us](https://mailchi.mp/spotify/backstage-community) in this next chapter of Backstage's journey. If you have questions or feedback, feel free to [email](mailto:backstage-interest@spotify.com) me directly. diff --git a/microsite/blog/2020-09-30-backstage-design-system.md b/microsite/blog/2020-09-30-backstage-design-system.md index 4faea98782..a1d087f755 100644 --- a/microsite/blog/2020-09-30-backstage-design-system.md +++ b/microsite/blog/2020-09-30-backstage-design-system.md @@ -68,9 +68,9 @@ To keep up with our latest design guidelines, go to [Designing for Backstage](ht ![img](assets/backstage-github-ds.png) -### [GitHub](https://github.com/spotify/backstage) +### [GitHub](https://github.com/backstage/backstage) -Join in on the action [at spotify/backstage on GitHub](https://github.com/spotify/backstage) by submitting issues and opening pull requests for all things related to components and patterns in Backstage. +Join in on the action [at backstage/backstage on GitHub](https://github.com/backstage/backstage) by submitting issues and opening pull requests for all things related to components and patterns in Backstage. ![img](assets/backstage-discord-DS.png) diff --git a/microsite/blog/2020-09-30-plugin-marketplace.md b/microsite/blog/2020-09-30-plugin-marketplace.md index 0b96abbc60..10928112b8 100644 --- a/microsite/blog/2020-09-30-plugin-marketplace.md +++ b/microsite/blog/2020-09-30-plugin-marketplace.md @@ -34,10 +34,10 @@ This grand vision is actually not that far off. Already today there is a growing Not all plugins you need will be open source. Every company has their own homegrown tooling. Building internal plugins lets you tailor your version of Backstage to be a perfect fit for your infrastructure and software development needs. If you end up [building plugins](https://backstage.io/docs/plugins/create-a-plugin) that could be useful for other companies, please consider releasing them as open source and [add them to the Marketplace](https://backstage.io/docs/plugins/add-to-marketplace). -If you start developing a plugin that you aim to release as open source, we suggest that you create a [new plugin Issue](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). This helps the community know what plugins are in development and opens up opportunities for collaboration. You can also use this process if you have an idea for a good plugin, but you need help building it. +If you start developing a plugin that you aim to release as open source, we suggest that you create a [new plugin Issue](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). This helps the community know what plugins are in development and opens up opportunities for collaboration. You can also use this process if you have an idea for a good plugin, but you need help building it. We are really excited to see all the amazing plugins that have already been built, and look forward to seeing even more ideas and collaboration as the Backstage community continues to grow. -What plugins would you like to see in the Plugin Marketplace? [Tell us](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME)! +What plugins would you like to see in the Plugin Marketplace? [Tell us](https://github.com/backstage/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME)! _Special shout-out to community member [Iain Billett](https://github.com/iain-b) from [Roadie](https://roadie.io) for helping build and contribute the [Plugin Marketplace page](https://backstage.io/plugins) (as his first PR no less!)._ diff --git a/microsite/blog/2020-10-22-cost-insights-plugin.md b/microsite/blog/2020-10-22-cost-insights-plugin.md new file mode 100644 index 0000000000..15647f8418 --- /dev/null +++ b/microsite/blog/2020-10-22-cost-insights-plugin.md @@ -0,0 +1,79 @@ +--- +title: New Cost Insights plugin: The engineer’s solution to taming cloud costs +author: Janisa Anandamohan +authorURL: https://twitter.com/janisa_a +--- + +How did Spotify save millions on cloud costs within a matter of months?? We made cost optimization just another part of the daily development process. Our newly open sourced [Cost Insights plugin](https://github.com/backstage/backstage/tree/master/plugins/cost-insights) makes a team’s cloud costs visible — and actionable — right inside Backstage. So engineers can see the impact of their cloud usage (down to a product and resource level) and make optimizations wherever and whenever it makes sense. By managing cloud costs from the ground up, you can make smarter decisions that let you continue to build and scale quickly, without wasting resources. + + + +Are we turning engineers into accountants? Nope, we’re just letting engineers do what they do best, in the place that feels natural to them: inside Backstage. + + + +## Why put a cost management tool in the hands of engineers? + +Engineers are closest to the metal in terms of knowing why a specific feature, product, or service is using cloud resources. So they’re in the best position to understand how costs impact ongoing development (and vice versa). + +If you manage costs top-down from a 10,000-foot view of your cloud infrastructure, you’re likely making decisions far removed from products, especially in larger organizations. Set a broad cost-cutting goal, and you could be creating unintended consequences — curtailing spending at the expense of growth or experimentation. + +## Ground-level intelligence, data-driven solutions + +Our hypothesis at Spotify was, if you bring spending data into an engineer’s everyday development workflow, they’ll naturally look for cost optimizations just like they look for any other optimization. And the cost optimizations will be more efficient and effective, because the decisions are informed at the ground level. + +The problem is that most cloud platforms don’t provide cost data at a granular enough level to make those decisions. And the bigger your organization (say, two-thousand-microservices and four-thousand-data-pipelines big, like Spotify), then the less you can attribute these large, fuzzy numbers to the right team, let alone a shipping product or internal service. + +That’s where Cost Insights comes in. Instead of making cost management and product development separate departments on the org chart, Backstage brings them together — with a level of detail and specificity engineers relate and respond to. + +## How to turn dollars into sense + +It’s not enough to make costs visible. To be useful, the numbers need to be relevant, relatable, and actionable. In other words, not just cost information, but insights. There are several ways the plugin puts data from your cloud provider in a more helpful context. + +### Use business metrics to evaluate costs + +Cost Insights will show you trends at a glance and also let you compare costs quarter over quarter. More importantly, you can also evaluate costs against business metrics that you care most about. In the example below, should the upward slope shown in the first screen be cause for worry? Perhaps not — if you switch views, you’ll see that cost per daily average user (DAU) is actually going down. Exactly what you hope to see as you scale. + +![Comparing costs to DAU](assets/20-10-22/cost-insights-1-dau.gif) +_(Note: Screens are examples; they do not show real data.)_ + +### Illustrate costs with relatable, real-world comparisons + +In addition to dollar amounts, Cost Insights allows teams to visualize and convert cost overages into more relatable terms. In the example below, we equate the growth in costs for virtual machine instances (100% increase) to developer time spent (about 1 engineer). We use this particular comparison in the plugin because we found it resonated with our own engineers — providing a useful perspective for spending increases. You can configure what the “cost of an engineer” means to your organization. Or engineers can build in their own comparisons — cups of coffee, carbon offset credits, electric luxury vehicles — whatever makes costs more tangible for them. + +![Cost growth as engineering time](assets/20-10-22/cost-insights-2-engineer.png) +_(Note: Screens are examples; they do not show real data.)_ + +### Tie spending to specific products and resources + +The more detailed the cost data, the more relevant, actionable, and helpful it is. Cost Insights allows you to attribute costs to products and resources in a way that makes sense to your engineers. For example, here we see a breakdown of data processing costs by individual pipelines. This allows your team to target optimizations more precisely. + +![Data Processing costs by pipeline](assets/20-10-22/cost-insights-3-data.png) +_(Note: Screens are examples; they do not show real data.)_ + +## Driving down costs without slowing down development + +When it comes to cutting costs, we actually want to guard against over-optimization. Growth and costs can go hand in hand. The trick is knowing when one is out of balance and needs addressing. Our product highlights when there’s been a large increase in spending, so that engineers are thinking about cost only when they must and aren’t distracted from their set goals and priorities. + +Engineers can then determine for themselves if the time invested in an optimization was valuable compared to the costs saved. Cost Insights puts the decision in our engineers’ hands for them to choose when to focus on growth efforts and when to focus on cost. Control, as ever, remains with our developers, where we think it belongs. + +## Getting started + +You can begin working with the Cost Insights plugin today on [GitHub](https://github.com/backstage/backstage/tree/master/plugins/cost-insights). We include an example client with static data in the expected format. The `CostInsightsApi` should talk with a cloud billing backend that aggregates billing data from your cloud provider. + +The current release of Cost Insights includes: + +- Daily cost graph by team or billing account +- Cost comparisons against configurable business metrics (including an option for Daily Active Users) +- Insights panels — configurable for the cloud products your company uses +- Cost alerts and recommendations +- Selectable time periods for month-over-month or quarter-over-quarter comparisons +- Conversion of cost growth into “cost of average engineer” to help optimization trade-off decisions + +Our hope is to help other companies translate their cloud cost in a relatable way for their engineers to better understand their impact and accurately identify their opportunities for optimizations. + +And if you’re interested in contributing to our outstanding issues, you can find them in the issues queue, filtered under the [‘cost-insights’ label](https://github.com/backstage/backstage/labels/cost-insights). + +## Ready for DevSecCostOpsPlus (and whatever’s next) + +There’s DevOps, there’s DevSecOps, and then there’s Backstage: one frontend for all your infrastructure. From building, testing, and deploying to monitoring and security — Backstage helps you manage your entire tech organization and provides a seamless developer experience for engineers, from end to end to end. And now that also extends to cost management for your cloud infrastructure and tooling. Happy building and [happy optimizing](https://github.com/backstage/backstage/tree/master/plugins/cost-insights). diff --git a/microsite/blog/assets/20-10-22/cost-insights-1-dau.gif b/microsite/blog/assets/20-10-22/cost-insights-1-dau.gif new file mode 100644 index 0000000000..df9396439d Binary files /dev/null and b/microsite/blog/assets/20-10-22/cost-insights-1-dau.gif differ diff --git a/microsite/blog/assets/20-10-22/cost-insights-2-engineer.png b/microsite/blog/assets/20-10-22/cost-insights-2-engineer.png new file mode 100644 index 0000000000..1e9293f5c1 Binary files /dev/null and b/microsite/blog/assets/20-10-22/cost-insights-2-engineer.png differ diff --git a/microsite/blog/assets/20-10-22/cost-insights-3-data.png b/microsite/blog/assets/20-10-22/cost-insights-3-data.png new file mode 100644 index 0000000000..941f0487da Binary files /dev/null and b/microsite/blog/assets/20-10-22/cost-insights-3-data.png differ diff --git a/microsite/core/Footer.js b/microsite/core/Footer.js index 1bebf2f399..6ce3c3dd84 100644 --- a/microsite/core/Footer.js +++ b/microsite/core/Footer.js @@ -17,19 +17,6 @@ const React = require('react'); class Footer extends React.Component { - docUrl(doc, language) { - const baseUrl = this.props.config.baseUrl; - const docsUrl = this.props.config.docsUrl; - const docsPart = `${docsUrl ? `${docsUrl}/` : ''}`; - const langPart = `${language ? `${language}/` : ''}`; - return `${baseUrl}${docsPart}${langPart}${doc}`; - } - - pageUrl(doc, language) { - const baseUrl = this.props.config.baseUrl; - return baseUrl + (language ? `${language}/` : '') + doc; - } - render() { return (