From 9698cbeff73bcf2ed1d94cb48c107c08b0767088 Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Mon, 19 Feb 2024 10:56:52 -0600 Subject: [PATCH 1/2] Expanded README with more context Signed-off-by: Andre Wanlin --- README.md | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 103 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b6b5f0f36..39ad87900 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,107 @@ # [Backstage Demo](https://demo.backstage.io) -Source code for the demo [Backstage](https://backstage.io/) instance deployed to [demo.backstage.io](https://demo.backstage.io). +[![Link to backstage-demo in Backstage Demo, Component: backstage-demo](https://demo.backstage.io/api/badges/entity/default/component/backstage-demo/badge/pingback 'Link to backstage-demo in Backstage Demo')](https://demo.backstage.io/catalog/default/component/backstage-demo) [![Entity docs badge, docs: backstage-demo](https://demo.backstage.io/api/badges/entity/default/component/backstage-demo/badge/docs 'Entity docs badge')](https://demo.backstage.io/catalog/default/component/backstage-demo/docs) + +This repository is the source code for the demo [Backstage](https://backstage.io/) instance deployed to [demo.backstage.io](https://demo.backstage.io). Instructions for building your own Backstage instance can be found at the [Getting Started](https://backstage.io/docs/getting-started/) portion of the docs. + +## Reference Project + +The sprit of this demo and repository is to showcase Backstage as closely as possible to what you would get from running `npx @backstage/create-app@latest` to create a new Backstage instance. There have been some additional changes beyond that starting point to help showcase some of Backstage's features more clearly. It also acts as a reference project for how to best keep it up to date and to show a working example of recent architecture patterns like the [new backend system](https://backstage.io/docs/backend-system/). + +## Core Features + +Here are the core features that come with Backstage and links to examples in the demo. + +- Software Catalog: +- Software Templates: +- Search: +- TechDocs: +- Kubernetes plugin: + +> Note: the Kubernetes plugin does need to be installed but is considered a core feature + +## Additional Plugins + +The following plugins have been added to help better illustrate Backstage features and to highlight the ability to add plugins. + +- Badges: See the badges at the top of this `README` +- Cost Insights: +- Explore: +- GitHub Actions: +- GraphiQL: +- Home: +- Tech Radar: +- To Do: + +## Code Customization + +We have made some code customization as well. The following sections go into detail about them. + +### Custom Theme + +We have created a custom theme called Aperture to help showcase what some of the possibilities a custom theme can allow and to have a working example. + +> Note: This theme is just an example and not intended to be copied as is. + +To view this theme in the Demo: + +1. Go to the Settings area here: +2. In the Appearance card for the Theme click on "APERTURE" +3. The theme will automatically change, now you can explore the Demo to see how this theme looks + +The Aperture custom theme code can be found in [`aperture.ts`](https://github.com/backstage/demo/blob/master/packages/app/src/theme/aperture.ts) + +More details on creating a custom theme can be found in the [Creating a Custom Theme](https://backstage.io/docs/getting-started/app-custom-theme#creating-a-custom-theme) documentation + +### Home Plugin + +Beyond the installation of the Home plugin to get the most out of it you need to setup the initial code for it. + +You can find the code here: + +We have also setup the more advanced feature of the Home plugin that allows you to customize it more easily, the code for that is here: + +To see the more advanced Home in the Demo site you will need to do the following: + +1. Go to the Settings area here: +2. Then click on the "FEATURE FLAGS" tab, which will take you here: +3. Next click on the toggle labeled "customizable-home-page-preview" +4. Now refresh the page, feature flags are not reactive by design +5. Navigate to the Home by clicking on the "Home" icon in the sidebar, which will take your here: +6. You should now see the more advanced Home, clicking on the "EDIT" button is a good place to start playing around with the features + +More details on the Home plugin can be found in the [Backstage homepage - Setup and Customization](https://backstage.io/docs/getting-started/homepage) documentation. + +### Search + +The Search plugin has been expanded to include results from the Explore plugins Tools list. This has been done in two places: + +1. Frontend changes are here: +2. Backend changes are here: + +> Note: currently Search is setup on the frontend to include results from TechDocs but it is disabled in the backend due to a [bug that happens with an unusual setup](https://github.com/backstage/backstage/issues/23047) like the Demo site. + +More information on adjusting search can be found in the [Customizing Search](https://backstage.io/docs/features/search/getting-started#customizing-search) documentation. + +## Upgrading + +This Demo site is kept in-sync with the weekly `next` release line as defined in the [Release Lines](https://backstage.io/docs/overview/versioning-policy#release-lines) documentation. Upgrading the Demo site has been automated so that a Pull Request with the latest changes is created the day after the weekly `next` release is published. This allows us to easily stay up to date! + +The automation is done using a GitHub workflow but the concepts and most of its parts could easily be transferred to other CI/CD systems like Azure DevOps Pipelines, CircleCI, etc. The parts of this workflow can be found here: + +- Core workflow: +- Related scripts: + +## Dependency Updates + +As Backstage uses packages for its various dependencies these will need to be kept up to date. This is terribly time consuming to do by hand thus we use [Renovate](https://github.com/renovatebot/renovate?tab=readme-ov-file#why-use-renovate) to help automate this process. Renovate will create Pull Requests for the various dependencies and all we need to to is review and merge them! + +You can see our Renovate configuration here: + +And example Pull Requests here: + +> Note: you may not see any Pull Request as we very much like to stay on top of them, clicking on the "Closed" option will let you see examples that have been merged in the past. + +To learn how to get started with Renovate we recommend reading the [Installing and onboarding Renovate into repositories](https://docs.renovatebot.com/getting-started/installing-onboarding/) documentation. From ed5bda129d933a0647180f5fbb33368ba72c8e99 Mon Sep 17 00:00:00 2001 From: Andre Wanlin Date: Sat, 24 Feb 2024 14:37:48 -0600 Subject: [PATCH 2/2] Changes based on feedback Signed-off-by: Andre Wanlin --- README.md | 59 ++++++++++++++++++++++++++----------------------------- 1 file changed, 28 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 39ad87900..6c7de7498 100644 --- a/README.md +++ b/README.md @@ -14,11 +14,11 @@ The sprit of this demo and repository is to showcase Backstage as closely as pos Here are the core features that come with Backstage and links to examples in the demo. -- Software Catalog: -- Software Templates: -- Search: -- TechDocs: -- Kubernetes plugin: +- [Software Catalog](https://demo.backstage.io/catalog) +- [Software Templates](https://demo.backstage.io/create) +- [Search](https://demo.backstage.io/search) +- [TechDocs](https://demo.backstage.io/docs) +- [Kubernetes plugin](https://demo.backstage.io/catalog/default/component/dice-roller) > Note: the Kubernetes plugin does need to be installed but is considered a core feature @@ -27,13 +27,13 @@ Here are the core features that come with Backstage and links to examples in the The following plugins have been added to help better illustrate Backstage features and to highlight the ability to add plugins. - Badges: See the badges at the top of this `README` -- Cost Insights: -- Explore: -- GitHub Actions: -- GraphiQL: -- Home: -- Tech Radar: -- To Do: +- [Cost Insights](https://demo.backstage.io/cost-insights) +- [Explore](https://demo.backstage.io/explore) +- [GitHub Actions](https://demo.backstage.io/catalog/default/component/backstage-demo/ci-cd) +- [GraphiQL](https://demo.backstage.io/graphiql) +- [Home](https://demo.backstage.io/home) +- [Tech Radar](https://demo.backstage.io/tech-radar) +- [To Do](https://demo.backstage.io/catalog/default/component/backstage-demo/todos) ## Code Customization @@ -41,17 +41,17 @@ We have made some code customization as well. The following sections go into det ### Custom Theme -We have created a custom theme called Aperture to help showcase what some of the possibilities a custom theme can allow and to have a working example. +We have created a custom theme called Aperture to help showcase what some of the possibilities are that a custom theme can allow and to have a working example. > Note: This theme is just an example and not intended to be copied as is. To view this theme in the Demo: -1. Go to the Settings area here: +1. Go to the [Settings area](https://demo.backstage.io/settings) 2. In the Appearance card for the Theme click on "APERTURE" 3. The theme will automatically change, now you can explore the Demo to see how this theme looks -The Aperture custom theme code can be found in [`aperture.ts`](https://github.com/backstage/demo/blob/master/packages/app/src/theme/aperture.ts) +The Aperture custom theme code can be found in the [`aperture.ts`](https://github.com/backstage/demo/blob/master/packages/app/src/theme/aperture.ts) file. More details on creating a custom theme can be found in the [Creating a Custom Theme](https://backstage.io/docs/getting-started/app-custom-theme#creating-a-custom-theme) documentation @@ -59,18 +59,17 @@ More details on creating a custom theme can be found in the [Creating a Custom T Beyond the installation of the Home plugin to get the most out of it you need to setup the initial code for it. -You can find the code here: +You can find the code in the [`HomePage.tsx`](https://github.com/backstage/demo/blob/master/packages/app/src/components/home/HomePage.tsx) file. -We have also setup the more advanced feature of the Home plugin that allows you to customize it more easily, the code for that is here: +We have also setup the more advanced feature of the Home plugin that allows you to customize it more easily, the code for that in [`CustomizableHomePage.tsx`](https://github.com/backstage/demo/blob/master/packages/app/src/components/home/CustomizableHomePage.tsx) To see the more advanced Home in the Demo site you will need to do the following: -1. Go to the Settings area here: -2. Then click on the "FEATURE FLAGS" tab, which will take you here: -3. Next click on the toggle labeled "customizable-home-page-preview" -4. Now refresh the page, feature flags are not reactive by design -5. Navigate to the Home by clicking on the "Home" icon in the sidebar, which will take your here: -6. You should now see the more advanced Home, clicking on the "EDIT" button is a good place to start playing around with the features +1. Go to the [feature flags area](https://demo.backstage.io/settings/feature-flags) +2. Next click on the toggle labeled "customizable-home-page-preview" +3. Now refresh the page, feature flags are not reactive by design +4. Navigate to the Home by clicking on the "Home" icon in the sidebar +5. You should now see the more advanced Home, clicking on the "EDIT" button is a good place to start playing around with the features More details on the Home plugin can be found in the [Backstage homepage - Setup and Customization](https://backstage.io/docs/getting-started/homepage) documentation. @@ -78,8 +77,8 @@ More details on the Home plugin can be found in the [Backstage homepage - Setup The Search plugin has been expanded to include results from the Explore plugins Tools list. This has been done in two places: -1. Frontend changes are here: -2. Backend changes are here: +1. Frontend changes are in the [`SearchPage.tsx`](https://github.com/backstage/demo/blob/master/packages/app/src/components/search/SearchPage.tsx) file +2. Backend changes are here the [`index.ts`](https://github.com/backstage/demo/blob/master/packages/backend/src/index.ts#L27) file > Note: currently Search is setup on the frontend to include results from TechDocs but it is disabled in the backend due to a [bug that happens with an unusual setup](https://github.com/backstage/backstage/issues/23047) like the Demo site. @@ -91,16 +90,14 @@ This Demo site is kept in-sync with the weekly `next` release line as defined in The automation is done using a GitHub workflow but the concepts and most of its parts could easily be transferred to other CI/CD systems like Azure DevOps Pipelines, CircleCI, etc. The parts of this workflow can be found here: -- Core workflow: -- Related scripts: +- [Core workflow](https://github.com/backstage/demo/blob/master/.github/workflows/version-bump.yml) +- [Related scripts](https://github.com/backstage/demo/blob/master/scripts/set-release-name.js) ## Dependency Updates -As Backstage uses packages for its various dependencies these will need to be kept up to date. This is terribly time consuming to do by hand thus we use [Renovate](https://github.com/renovatebot/renovate?tab=readme-ov-file#why-use-renovate) to help automate this process. Renovate will create Pull Requests for the various dependencies and all we need to to is review and merge them! +As Backstage uses packages for its various dependencies these will need to be kept up to date. We use [Renovate](https://github.com/renovatebot/renovate?tab=readme-ov-file#why-use-renovate) as it is incredibly helpful in keeping dependency versions up to date. Renovate will create Pull Requests for the various dependencies and all we need to to is review and merge them! -You can see our Renovate configuration here: - -And example Pull Requests here: +You can see our Renovate configuration in the [`renovate.json`](https://github.com/backstage/demo/blob/master/renovate.json) file and example [Pull Requests here](https://github.com/backstage/demo/pulls?q=is%3Aopen+is%3Apr+label%3Adependencies) > Note: you may not see any Pull Request as we very much like to stay on top of them, clicking on the "Closed" option will let you see examples that have been merged in the past.