From 8f6bf6b4e796d42238604981919d8c4b3e876a31 Mon Sep 17 00:00:00 2001 From: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> Date: Fri, 13 Feb 2026 14:20:32 -0500 Subject: [PATCH] docs: adding more golden path docs (#32493) * docs: adding more golden path docs Signed-off-by: aramissennyeydd * cleanup Signed-off-by: aramissennyeydd * add instructions for checking todo list items Signed-off-by: aramissennyeydd * update ids so the number isn't baked into URL Signed-off-by: aramissennyeydd * add headings for all docs Signed-off-by: aramissennyeydd * add frontend plugin docs structure too Signed-off-by: aramissennyeydd * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> * fix bad link Signed-off-by: aramissennyeydd * address feedback Signed-off-by: aramissennyeydd * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> --------- Signed-off-by: aramissennyeydd Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../adoption/001-getting-started.md | 72 +++++++++++++++++++ .../adoption/002-leadership-buy-in.md | 30 ++++++++ .../adoption/003-setting-up-a-poc.md | 13 ++++ .../004-first-stakeholder-feedback.md | 17 +++++ .../adoption/005-customizing-your-instance.md | 15 ++++ .../adoption/006-preparing-for-ga.md | 19 +++++ .../adoption/007-plugin-ownership.md | 17 +++++ docs/golden-path/adoption/008-full-catalog.md | 15 ++++ .../adoption/{meta.md => __meta__.md} | 6 +- .../deployment/{meta.md => __meta__.md} | 0 docs/golden-path/deployment/index.md | 0 docs/golden-path/plugins/__meta__.md | 15 ++++ .../plugins/backend/001-first-steps.md | 2 +- .../plugins/backend/002-poking-around.md | 41 ++++++++++- .../plugins/backend/003-persistence.md | 19 +++++ .../plugins/backend/004-source-tracked.md | 19 +++++ .../plugins/backend/005-testing.md | 29 ++++++++ docs/golden-path/plugins/backend/__meta__.md | 39 ++-------- docs/golden-path/plugins/backend/todo.http | 12 ---- .../plugins/frontend/001-first-steps.md | 15 ++++ .../plugins/frontend/002-poking-around.md | 17 +++++ .../plugins/frontend/003-dynamic-config.md | 29 ++++++++ .../plugins/frontend/004-http-client.md | 17 +++++ .../plugins/frontend/005-testing.md | 15 ++++ docs/golden-path/plugins/frontend/__meta__.md | 34 +++++++++ .../plugins/integrations/001-catalog.md | 23 ++++++ .../plugins/integrations/002-search.md | 19 +++++ .../plugins/integrations/003-permissions.md | 23 ++++++ .../plugins/integrations/004-notifications.md | 23 ++++++ 29 files changed, 541 insertions(+), 54 deletions(-) create mode 100644 docs/golden-path/adoption/001-getting-started.md create mode 100644 docs/golden-path/adoption/002-leadership-buy-in.md create mode 100644 docs/golden-path/adoption/003-setting-up-a-poc.md create mode 100644 docs/golden-path/adoption/004-first-stakeholder-feedback.md create mode 100644 docs/golden-path/adoption/005-customizing-your-instance.md create mode 100644 docs/golden-path/adoption/006-preparing-for-ga.md create mode 100644 docs/golden-path/adoption/007-plugin-ownership.md create mode 100644 docs/golden-path/adoption/008-full-catalog.md rename docs/golden-path/adoption/{meta.md => __meta__.md} (98%) rename docs/golden-path/deployment/{meta.md => __meta__.md} (100%) create mode 100644 docs/golden-path/deployment/index.md create mode 100644 docs/golden-path/plugins/__meta__.md create mode 100644 docs/golden-path/plugins/backend/003-persistence.md create mode 100644 docs/golden-path/plugins/backend/004-source-tracked.md create mode 100644 docs/golden-path/plugins/backend/005-testing.md delete mode 100644 docs/golden-path/plugins/backend/todo.http create mode 100644 docs/golden-path/plugins/frontend/001-first-steps.md create mode 100644 docs/golden-path/plugins/frontend/002-poking-around.md create mode 100644 docs/golden-path/plugins/frontend/003-dynamic-config.md create mode 100644 docs/golden-path/plugins/frontend/004-http-client.md create mode 100644 docs/golden-path/plugins/frontend/005-testing.md create mode 100644 docs/golden-path/plugins/frontend/__meta__.md create mode 100644 docs/golden-path/plugins/integrations/001-catalog.md create mode 100644 docs/golden-path/plugins/integrations/002-search.md create mode 100644 docs/golden-path/plugins/integrations/003-permissions.md create mode 100644 docs/golden-path/plugins/integrations/004-notifications.md diff --git a/docs/golden-path/adoption/001-getting-started.md b/docs/golden-path/adoption/001-getting-started.md new file mode 100644 index 0000000000..574380f263 --- /dev/null +++ b/docs/golden-path/adoption/001-getting-started.md @@ -0,0 +1,72 @@ +--- +id: getting-started +sidebar_label: 001 - Getting started +title: Getting started with Backstage +--- + +The adoption journey is a bit different than the other Golden Paths. The goal of this guide is to prepare you for a successful implementation of Backstage in your organization. A technical understanding of Backstage is not needed for this Golden Path, just a desire to help the technical team that will be owning your Backstage instance. + +:::info + +I'd highly recommend poking around https://demo.backstage.io/ before continuing with this guide. It's a test instance of Backstage that provides a good foundation for what to expect from the tool as a user. + +::: + +## What is Backstage? + +At a high level, Backstage is a framework for building developer portals. When implemented successfully, it can reduce toil for your developers by centralizing information like docs and ownership, reducing cognitive overhead due to tool fragmentation and simplify setting up new codebases or integrating with existing ones. + +A few examples, + +> My company tracks everything with spreadsheets. We have a list of all Github repos and who owns them, but it's becoming more and more of an issue to keep up to date. Teams aren't proactively updating it when new projects are created and it quickly falls out of date with reorgs and team charter changes. + +Backstage can help! We provide a core plugin called Software Catalog that automates this process. Teams are asked to maintain a file in their repo with this ownership information and it gets automatically ingested into Backstage where you can view all projects in a single location. + +> My developers have been complaining recently about having to use a growing number of different websites and tools in their day to day. It's getting hard to keep track of all of the tools and for those that we don't use frequently, we lose X minutes trying to remember how to access them. + +Tool fragmentation is a real issue and Backstage can also help here! You can create plugins tailored for your company that talk to these external services. These plugins can be standalone or integrated with the Software Catalog for better context. Imagine all of your [CI/CD workflows visible directly](https://backstage.io/plugins/) on the page for your team's projects. + +It's important to note that Backstage shouldn't be fully replacing these tools, we don't want to reinvent the wheel. The goal is to have all of the really important information in one place. The tool should still be where teams go to do more advanced or in depth work. + +> We have been struggling recently with getting teams to use a standard template for new services. There's no standard set of libraries these services are using or standard infra management. It's increasingly difficult as a platform team to manage everything. + +Backstage can help here too! The Scaffolder provides a templating framework that you can plug a Golden Path implementation to. Similar to Github template repos, this can provide a standard base for teams to create based off of. + +> Our platform teams have been getting more and more support requests to help debug onboarding steps. We've documented these areas really well and there are plenty of examples in Git, but teams keep running into the same issues. It's always either a bad copy paste or they forget to update a template variable. We've started looking into a custom templating solution for this. + +Backstage can help! With the Scaffolder, you can create a template that lets users fill in data through a form and uses that data to create a customized template output. This output is usually in the form of PRs to your various source control systems. Imagine you have a repo for traffic configuration, another for infrastructure management and a third for k8s manifests - with the Scaffolder, you can hide all of this complexity. You may still need to get reviews on the output PRs, but no more copy paste issues! + +## What does adopting Backstage look like? + +a.k.a "what am I signing myself up for?" + +Successfully adopting Backstage usually looks something like this, + +1. Setting up a PoC. +2. Getting leadership buy-in. +3. Identify a group of key stakeholders for the project and iterate with them aggressively. +4. Launch to the larger organization. +5. Drive Catalog adoption to 100%. +6. Your Backstage implementation starts to receive plugins from developers outside of your team. + +A truly successful Backstage implementation bridges delivering value to customers (developers), demonstrating returns to leadership, and fostering an inner source model. It's a long process but has huge dividends for those that achieve it! + +## Getting started + +Now that you know what to expect, let's walk through how to get started. + +:::note + +If you're non-technical, it is highly recommended to find a technical partner for help setting up a proof-of-concept for feedback. + +::: + +### Software Catalog + +Let's go to https://demo.backstage.io/ together. When you first navigate to the page, you will be brought to the Software Catalog page. This is a view of all projects currently registered with the (Demo) Backstage instance. There are a series of filters that you can play around with. If you're _really_ interested, we recommend reading through [the software catalog system model](../../features/software-catalog/system-model.md). + +Let's click into a Component, say "artist-lookup". This will bring you to a specialized view for that Component. Across the top, you can see tabs for "CI/CD", "API", "Dependencies", "Docs" and "TODOs". For your company, you can change this as you see fit. The important takeaway is that all of these tabs are automatically filtered for this Component which makes it easy to see how this could start to replace many navigation to other tools. + +### Scaffolder + +Let's go to https://demo.backstage.io/create now. This is the Scaffolder, a place to store reusable templates. Click the "Choose" button in the "Demo template". This will bring you to a form with some information to input. You don't need to fill this out. The main takeaway here is that this form is generated from YAML and doesn't require a frontend team to implement a custom form for each template you want to create. diff --git a/docs/golden-path/adoption/002-leadership-buy-in.md b/docs/golden-path/adoption/002-leadership-buy-in.md new file mode 100644 index 0000000000..502970d3dc --- /dev/null +++ b/docs/golden-path/adoption/002-leadership-buy-in.md @@ -0,0 +1,30 @@ +--- +id: leadership-buy-in +sidebar_label: 002 - Leadership buy-in +title: Getting leadership buy-in +--- + +## Summary + +In this section, we'll be going over what leadership needs to hear to buy in to your pitch for a developer portal. We expect that you have a good idea of the problem that you want Backstage to solve at your company. If not, we recommend you start small. Look for something that is consistently frustrating developers you work with (this can include you). User interviews are a great way to better understand what needs to improve. It may be IT blocking the creation of new Github repos or databases. It might be 5 hours per week of manual toil that your whole organization has to do. It might be a slow time to production for new services or slow provisioning of test environments. Every company will be different. There is no one size fits all answer we can give you - and if we could, it wouldn't be well-tailored for _your_ leadership team. + +## Milestones + +Every Backstage adoption journey has well-known milestones. + +1. You set up a PoC. +2. You get some users. +3. A group of users _really_ gets the value in the portal and jumps on it. They may even create their own plugins - great! +4. You start to plateau with catalog adoption or daily active users. +5. Leadership starts to get nosy about continued value. +6. You hit a crossroads. Your team either starts to think about building something themselves or going for another off the shelf option or they sit down and do the work to get out of the plateau. +7. If your organization made it this far, you likely now have blocking checks for catalog entries and Backstage is a weekly if not daily portal for your developers - congrats! + +Step 4 and 5 are painful moments. Successful Backstage adoptions can lose steam quickly. That's the nature of these things, the excitement will eventually run out and people will go back to their day jobs. Another YAML file or cataloging tool is just overhead and extra toil, regardless of the problem you're solving. Getting leadership on the same page about the value of Backstage is the first step to a very successful adoption story. + +### Recommendations + +1. Bring something real to your leadership team. This can either be a true proof of concept or [the demo site](https://demo.backstage.io). +2. Define metrics around what you're looking to drive up/down. That may be time to onboarding a new engineer, time to production for a new service, time to mitigate incidents, etc. As we say above, this is the meaty problem that is unique to your company that solving will really move the needle. +3. Lower the barrier to adoption. Many people see yet another YAML file as overhead. If you have an existing cataloging solution, use that to simplify the onboarding process. If you don't, this might be a good opportunity to do that work. +4. Knowledge silos. Every team has preferences on how to do things. Centralizing that data into a single interface while letting teams continue to do things how they want to is a powerful goal and something that Backstage can make happen. diff --git a/docs/golden-path/adoption/003-setting-up-a-poc.md b/docs/golden-path/adoption/003-setting-up-a-poc.md new file mode 100644 index 0000000000..155098c357 --- /dev/null +++ b/docs/golden-path/adoption/003-setting-up-a-poc.md @@ -0,0 +1,13 @@ +--- +id: setting-up-a-poc +sidebar_label: 003 - Setting up a PoC +title: Setting up a PoC +--- + +If you're non-technical, this section should be completed by your technical partner. + +Follow [our golden path for creating an app](../create-app/index.md). Once you have that set up, we recommend adding a few `catalog-info.yaml` files to a few repos/projects you own and setting up [the GitHub catalog provider](../../integrations/github/discovery.md). + +At this stage, you likely want to just get the instance running on your local machine. We'll go over preparing your instance for production at the end of chapter 2. + +You may be tempted to update the theme or add that one plugin your organization _needs_, but hold strong. We'll get there in chapter 3. diff --git a/docs/golden-path/adoption/004-first-stakeholder-feedback.md b/docs/golden-path/adoption/004-first-stakeholder-feedback.md new file mode 100644 index 0000000000..6207a49d10 --- /dev/null +++ b/docs/golden-path/adoption/004-first-stakeholder-feedback.md @@ -0,0 +1,17 @@ +--- +id: first-stakeholder-feedback +sidebar_label: 004 - Stakeholder Feedback +title: First round of stakeholder feedback +--- + +Now that you have a PoC running, let's walk through how to get good feedback. You likely aren't the first person to hear about Backstage or maybe not even the first person to set up a PoC. There may be common pitfalls unique to your company that are worth knowing about - political, organizational or otherwise. + +## Who to look for? + +This depends pretty significantly on your organizational structure. If you have a dedicated platform organization or platform team, start with them. They will either be the technical owners of this application from the go, or will eventually take over ownership. Be kind to them. If you aren't from that organization, we recommend finding your technical partner from somewhere in that organization. + +## What to listen for + +1. IT slowness. Does your organization run on tickets? Are there specific tasks that feel like they should be automated but aren't? +2. User toil. Your developers are super aware of what's slowing them down, they'll tell you the annoying manual parts of their job that they're hoping you can fix. +3. Data sprawl. What services are your users struggling to remember? What vendors are critical but most users only touch once a month? diff --git a/docs/golden-path/adoption/005-customizing-your-instance.md b/docs/golden-path/adoption/005-customizing-your-instance.md new file mode 100644 index 0000000000..9cc9a98d7a --- /dev/null +++ b/docs/golden-path/adoption/005-customizing-your-instance.md @@ -0,0 +1,15 @@ +--- +id: customize-your-instance +sidebar_label: 005 - Customizing your instance +title: Customizing your instance +--- + +You now have the knowledge of what your users want and the go from leadership to continue investing in Backstage. Your job now is to customize your instance for your users to really get the value from. Let's dive in! + +## Open Source or Build it yourself? + +There's a huge community of plugins available for easy installation at https://backstage.io/plugins. We would recommend that you start here for any needs you may be trying to solve. Building a plugin yourself requires significant effort and can be hard to justify early on in your adoption story. If there is a clear gap in the existing offerings for your company, you should build something yourself - otherwise, save yourself the maintenance overhead. + +## Customizing the theme + +Many organizations are tempted to spend a long time making sure the portal resembles their other offerings. This is important but shouldn't be a months long ordeal. Get it looking close enough and iterate. diff --git a/docs/golden-path/adoption/006-preparing-for-ga.md b/docs/golden-path/adoption/006-preparing-for-ga.md new file mode 100644 index 0000000000..0b62f0fa25 --- /dev/null +++ b/docs/golden-path/adoption/006-preparing-for-ga.md @@ -0,0 +1,19 @@ +--- +id: preparing-for-ga +sidebar_label: 006 - Preparing for GA +title: Preparing for GA +--- + +We hope at this point that the developers you're working with have read the [golden path on deploying Backstage](../deployment/index.md). Your Backstage instance should be ready for the scale that comes with a full company launch. + +## Launch Announcements + + + +## What to expect in the coming months + + + +## How to keep iterating + + diff --git a/docs/golden-path/adoption/007-plugin-ownership.md b/docs/golden-path/adoption/007-plugin-ownership.md new file mode 100644 index 0000000000..17455f19e7 --- /dev/null +++ b/docs/golden-path/adoption/007-plugin-ownership.md @@ -0,0 +1,17 @@ +--- +id: plugin-ownership +sidebar_label: 007 - Plugin Ownership +title: Plugin Ownership +--- + +You're now well on your way to a healthy Backstage instance! It's been launched to the whole company and you're loving the feedback developers are giving you. Some developers have even started broaching writing their own plugins. + +## Inner source + +Accepting internal contributions from other teams is a good sign that you are on the road to a developer portal tailored for your developers. This is a well paved path with many upsides, but a few downsides as well. As your Backstage instance grows in size and age, those same developers may be difficult to find. Your team may start to experience more and more struggle updating Backstage. + + + +## Registering Plugins in Your Catalog + + diff --git a/docs/golden-path/adoption/008-full-catalog.md b/docs/golden-path/adoption/008-full-catalog.md new file mode 100644 index 0000000000..1725bf6dd2 --- /dev/null +++ b/docs/golden-path/adoption/008-full-catalog.md @@ -0,0 +1,15 @@ +--- +id: full-catalog +sidebar_label: 008 - A Full Catalog +title: Ensuring your catalog stays complete +--- + +Along your Backstage journey (and any workflow migration journey), you will hit a point where incremental adoption is no longer easy. The new developers are no longer flowing into your tool like they once did. More and more projects are not being listed in your catalog. Something has to change. + +## Enforcing Catalog Files in CI + + + +## Leadership Initiatives + + diff --git a/docs/golden-path/adoption/meta.md b/docs/golden-path/adoption/__meta__.md similarity index 98% rename from docs/golden-path/adoption/meta.md rename to docs/golden-path/adoption/__meta__.md index 1c4756d8ee..05fd50a2f6 100644 --- a/docs/golden-path/adoption/meta.md +++ b/docs/golden-path/adoption/__meta__.md @@ -19,6 +19,8 @@ Users should already have read through the summary section of the docs, "What is We recommend you poke around the demo site to get a feel for what Backstage can provide. If you're technical, or working with someone technical, you can run through the steps in `golden-path/create-app` and `golden-path/deploying-backstage` to get something running for just your company. +## Getting leadership buy-in + ## First round of stakeholder feedback If you think Backstage is a good fit for your company, it's likely there are others that do or will think the same. You may have already identified them. For this initial round of feedback, share recommendations for what that group should look like, is there any required number of technical or non-technical members, do you need leadership involved at this point, etc. @@ -29,9 +31,7 @@ For non-technical users, it's recommended to find a technical partner to help st At this point, we're assuming you already have an instance created through `golden-path/create-app` and `golden-path/deploying-backstage`. You should now start customizing it to your company's needs. We recommend you start small, write some catalog-info YAML files and start to build a personalized catalog. -## Second round of stakeholder feedback - -## Getting leadership buy-in +## Preparing for GA ## Plugin ownership and inner source mentality diff --git a/docs/golden-path/deployment/meta.md b/docs/golden-path/deployment/__meta__.md similarity index 100% rename from docs/golden-path/deployment/meta.md rename to docs/golden-path/deployment/__meta__.md diff --git a/docs/golden-path/deployment/index.md b/docs/golden-path/deployment/index.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/golden-path/plugins/__meta__.md b/docs/golden-path/plugins/__meta__.md new file mode 100644 index 0000000000..ab19c569d9 --- /dev/null +++ b/docs/golden-path/plugins/__meta__.md @@ -0,0 +1,15 @@ + + +## Why build plugins? + +This section should clearly explain why you should build a new plugin. The Backstage framework is deeply empowered by plugins and plugins are core to the project's success. Users should walk away from reading this section with a conviction that plugins are the right path for new functionality. + +## Sustainable plugin development + +Plugins are not developed in a vacuum. Users should reach for them to solve specific business problems facing their developers, for example, you may be tasked to create + +- a new vendor integration like PagerDuty, +- a new plugin backend that talks to an internal service, +- etc. + +This section should contain learnings from successful Backstage deployments about how to engage with stakeholders, how/when to iterate on your plugin, and setting yourself up for future success. diff --git a/docs/golden-path/plugins/backend/001-first-steps.md b/docs/golden-path/plugins/backend/001-first-steps.md index 1850ba52c1..8a0defe183 100644 --- a/docs/golden-path/plugins/backend/001-first-steps.md +++ b/docs/golden-path/plugins/backend/001-first-steps.md @@ -1,5 +1,5 @@ --- -id: 001-first-steps +id: first-steps sidebar_label: 001 - Scaffolding the plugin title: How to scaffold a new plugin? --- diff --git a/docs/golden-path/plugins/backend/002-poking-around.md b/docs/golden-path/plugins/backend/002-poking-around.md index 35de3c4d47..596de01b4b 100644 --- a/docs/golden-path/plugins/backend/002-poking-around.md +++ b/docs/golden-path/plugins/backend/002-poking-around.md @@ -1,5 +1,5 @@ --- -id: 002-poking-around +id: poking-around sidebar_label: 002 - Poking around title: 002 - Poking around --- @@ -16,7 +16,7 @@ To make this plugin production ready, we'll need to adjust a few things, ## Testing locally -Before we jump in to making this plugin ready to ship, let's walk through how to run it locally. If you open your backend plugin's manifest (`plugins/todo-backend/package.json`), and look at the `scripts` section, you'll notice a few important commands. The ones relevant to use right now are +Before we jump in to making this plugin ready to ship, let's walk through how to run it locally. If you open your backend plugin's manifest (`plugins/todo-backend/package.json`), and look at the `scripts` section, you'll notice a few important commands. The ones relevant to us right now are 1. `yarn start` - Starts a local development server using the content in `dev/index.ts` as the backend. 2. `yarn test` - Runs all of the tests for your backend plugin. @@ -27,8 +27,43 @@ If you run `yarn start`, you should see a custom backend for just your plugin st 2025-06-08T16:14:53.229Z rootHttpRouter info Listening on :7007 ``` -This indicates that your HTTP server is up and running and we can start sending test HTTP requests. Grab your favorite HTTP client and let's get testing! If you aren't sure what to use, I'd recommend the `humao.rest-client` VSCode extension which can easily be run in VSCode itself with very little extra set up. +This indicates that your HTTP server is up and running and we can start sending test HTTP requests. Grab your favorite HTTP client and let's get testing! +To start, let's make sure we're starting from a clean slate. You can list all existing TODOs by running the command below. You should get back an empty list: + +```sh +curl http://localhost:7007/api/todo/todos ``` +To create a new TODO, you can send a POST request to the same endpoint. However, you will get a 401 error right now. + +```sh +curl -X POST http://localhost:7007/api/todo/todos \ +-H 'Content-Type: application/json; charset=utf-8' \ +--data-binary @- << EOF +{ + "title": "My Todo" +} +EOF ``` + +The 401 error is because we track the ID of the user that created each TODO. If you send a request to create a TODO but don't provide an `Authorization` header, you will see this failure. For plugins that have a frontend as well, this credential management should happen automatically. Let's try this: + +```sh +curl -v -X POST http://localhost:7007/api/todo/todos \ +-H 'Content-Type: application/json; charset=utf-8' \ +-H "Authorization: Bearer $(curl -s http://localhost:7007/api/auth/guest/refresh | jq -r '.backstageIdentity.token')" \ +--data-binary @- << EOF +{ + "title": "My Todo" +} +EOF +``` + +We can then list all TODOs to see our new TODO! + +```sh +curl http://localhost:7007/api/todo/todos +``` + +You'll notice that `createdBy` is `user:development/guest` which is the token we used to create the TODO. That's the `-H "Authorization: Bearer $(curl -s http://localhost:7007/api/auth/guest/refresh | jq -r '.backstageIdentity.token')"` part of the request. diff --git a/docs/golden-path/plugins/backend/003-persistence.md b/docs/golden-path/plugins/backend/003-persistence.md new file mode 100644 index 0000000000..ba00b2f417 --- /dev/null +++ b/docs/golden-path/plugins/backend/003-persistence.md @@ -0,0 +1,19 @@ +--- +id: persistence +sidebar_label: 003 - Persisting your TODOs +title: 003 - Persisting your TODOs +--- + +## Saving Plugin State Indefinitely + +You may have noticed that your list of TODOs disappears after you restart your Backstage backend. The general flow to restart your backend without having to rerun `yarn start` is to press ENTER on the terminal running `yarn start`. This will force the Backstage backend to restart completely, wiping out any in memory data and starting everything from scratch -- everything except your database. + +### Quick intro to SQLite + +SQLite is the default database for local development. It runs in memory (and can also run from a file on disk). It supports quick iteration cycles and can be easily deleted if anything goes wrong. + +## Adding the `databaseService` to your plugin + + + +## Testing your changes diff --git a/docs/golden-path/plugins/backend/004-source-tracked.md b/docs/golden-path/plugins/backend/004-source-tracked.md new file mode 100644 index 0000000000..074cc85cf1 --- /dev/null +++ b/docs/golden-path/plugins/backend/004-source-tracked.md @@ -0,0 +1,19 @@ +--- +id: source-tracked +sidebar_label: 004 - Integrating with SCMs +title: 004 - Git-tracked TODOs +--- + +Problem: You have TODOs in your source code that you want to ingest with your plugin. + +## Authenticating + + + +## Querying + + + +## Fetching + + diff --git a/docs/golden-path/plugins/backend/005-testing.md b/docs/golden-path/plugins/backend/005-testing.md new file mode 100644 index 0000000000..9643e8a487 --- /dev/null +++ b/docs/golden-path/plugins/backend/005-testing.md @@ -0,0 +1,29 @@ +--- +id: testing +sidebar_label: 005 - Unit testing your plugin +title: 005 - Testing +--- + +## Testing is important + +We've done a lot of manual testing up to this point of functionality. Let's start putting those assumptions into code that we can run on every change to ensure things are working correctly. + +## Router-level testing + + + +## Plugin-level testing + + + +## OpenAPI testing + + + +### Integration with Jest tests + + + +### Fuzzing + + diff --git a/docs/golden-path/plugins/backend/__meta__.md b/docs/golden-path/plugins/backend/__meta__.md index e261a8f970..d78e6a7573 100644 --- a/docs/golden-path/plugins/backend/__meta__.md +++ b/docs/golden-path/plugins/backend/__meta__.md @@ -1,36 +1,7 @@ -# Glossary - -- Page: A single `md` file. -- Guide: A number of pages grouped under the same folder. - -# Overall Writing Guidelines - -The goal of these docs is to provide a comprehensive set of guides that developers + admins can use to quickly get up to speed with plugin development, and then refer to as they're developing their own plugins. - -A user that finishes all of these guides will feel comfortable implementing plugins on their own. If additional assistance is required, they should be referred to other sources of information such as Discord, GitHub, source code, or documentation for further support. The user will also understand why/when to build their own plugins, inner-sourcing their developer portal and contributing internal plugins back to the open-source project. - -At the same time, not all users will finish the docs or they may come back to them as required. Individual guides should have strong "abstracts" (what will I learn by reading this guide), table of contents, and "next steps" (what do I need to do next) to guide users to read the most important pieces for their work. - -When writing guide pages, keep it light! These should be instructional docs, and at the same time conversational and a joy to read. Guides should build on each other, when reading through a progression, the reader should feel more comfortable and confident with concepts as they pop up across progression levels. Guides should be standalone, when finishing one level (for example 101), you should be able to immediately jump into the next (201) without additional research or background. Referencing previous progression levels is ok. - # Sections -## Why build plugins? - -This section should answer definitely why you should build a new plugin. The Backstage framework is deeply empowered by plugins and plugins are core to the project's success. Users should walk away from reading this section with a conviction that plugins are the right path for new functionality. - -## Sustainable plugin development - -Plugins are not developed in a vacuum. Users should reach for them to solve specific business problems facing their developers, for example, you may be tasked to create - -- a new vendor integration like PagerDuty, -- a new plugin backend that talks to an internal service, -- etc. - -This section should contain learnings from successful Backstage deployments about how to engage with stakeholders, how/when to iterate on your plugin, and setting yourself up for future success. - ## Creating your first plugin This section should be extremely deliberate in showing readers every step of the way to create a plugin using Backstage's best practices. A reader that finishes this section should feel extremely comfortable creating new plugins and how to install and use plugins regardless of their experience with JS/TS and Backstage. @@ -78,12 +49,6 @@ app.get('/list', async (req, res) => { }); ``` -### Testing - -Let's write a unit test using `supertest` to make sure that everything is working as expected. - -After verifying everything, introduce the problem of persistence - the todos aren't saved across reloads. - ### Persistence Saving values to the database. Writing a migrations file. Plumbing through the database service. @@ -91,3 +56,7 @@ Saving values to the database. Writing a migrations file. Plumbing through the d ## SCM Integrations Our users love the new plugin, and now they want it to automatically fetch todos from their source code. + +### Testing + +Let's write a unit test using `supertest` to make sure that everything is working as expected. diff --git a/docs/golden-path/plugins/backend/todo.http b/docs/golden-path/plugins/backend/todo.http deleted file mode 100644 index 932dcb76e4..0000000000 --- a/docs/golden-path/plugins/backend/todo.http +++ /dev/null @@ -1,12 +0,0 @@ -POST http://localhost:7007/api/todo/todos -Content-Type: application/json - -{ - "title": "My First TODO" -} - -### - -GET http://localhost:7007/api/todo/todos - -### \ No newline at end of file diff --git a/docs/golden-path/plugins/frontend/001-first-steps.md b/docs/golden-path/plugins/frontend/001-first-steps.md new file mode 100644 index 0000000000..d6c21ed053 --- /dev/null +++ b/docs/golden-path/plugins/frontend/001-first-steps.md @@ -0,0 +1,15 @@ +--- +id: first-steps +sidebar_label: 001 - Scaffolding the plugin +title: How to scaffold a new plugin? +--- + +Running `yarn new` -> `frontend-plugin`. + +## What did we create? + + + +## Common issues + + diff --git a/docs/golden-path/plugins/frontend/002-poking-around.md b/docs/golden-path/plugins/frontend/002-poking-around.md new file mode 100644 index 0000000000..e85ea235f3 --- /dev/null +++ b/docs/golden-path/plugins/frontend/002-poking-around.md @@ -0,0 +1,17 @@ +--- +id: poking-around +sidebar_label: 002 - Poking around +title: 002 - Poking around +--- + +Our frontend TODO plugin is a bit more simplistic than the backend one. We need to implement a new UI to replace the example components we have. + +Let's use this React component to start. Copy this to `plugins/todo/src/components/TodoList.tsx`. + +```tsx +// todo +``` + +### Data Mocking + +You already have a backend with dynamic data. Let's start a little smaller. Using hard coded data can be a great way to iterate quickly. diff --git a/docs/golden-path/plugins/frontend/003-dynamic-config.md b/docs/golden-path/plugins/frontend/003-dynamic-config.md new file mode 100644 index 0000000000..8eecd72c2f --- /dev/null +++ b/docs/golden-path/plugins/frontend/003-dynamic-config.md @@ -0,0 +1,29 @@ +--- +id: dynamic-config +sidebar_label: 003 - Dynamic Config +title: 003 - Dynamic Config +--- + +Your plugin should have been generated by default for the New Frontend System which is config-first. That means you can easily control your frontend components through your `app-config.yaml`. + +Let's try this quickly by disabling our entire TODO page, + +```yaml +# TODO +``` + +We can also do really cool things like provide React props directly through config. Let's try moving our hard coded list of TODOs to config instead, + +```tsx +// todo +``` + +and the config, + +```yaml +# TODO +``` + +### Why does this work? + + diff --git a/docs/golden-path/plugins/frontend/004-http-client.md b/docs/golden-path/plugins/frontend/004-http-client.md new file mode 100644 index 0000000000..b6190f0f5f --- /dev/null +++ b/docs/golden-path/plugins/frontend/004-http-client.md @@ -0,0 +1,17 @@ +--- +id: http-client +sidebar_label: 004 - HTTP Client +title: 004 - HTTP Client +--- + +Now, let's really make our page dynamic. We'll start by writing an HTTP client by hand. + +```tsx +class TodoClient { + // TODO +} +``` + +## OpenAPI Generated Clients + +You can also skip a step and ensure your frontend and backend stay in sync by generating the client from an OpenAPI schema. diff --git a/docs/golden-path/plugins/frontend/005-testing.md b/docs/golden-path/plugins/frontend/005-testing.md new file mode 100644 index 0000000000..fe385d7169 --- /dev/null +++ b/docs/golden-path/plugins/frontend/005-testing.md @@ -0,0 +1,15 @@ +--- +id: testing +sidebar_label: 005 - Testing +title: 005 - Testing +--- + +Everyone's favorite part! Let's make sure our components continue to work even when we're not able to validate the changes. + +## Unit Tests + +Use Jest + RTL + MSW v2. + +## Integration Tests + +Use Playwright. diff --git a/docs/golden-path/plugins/frontend/__meta__.md b/docs/golden-path/plugins/frontend/__meta__.md new file mode 100644 index 0000000000..088d72ce90 --- /dev/null +++ b/docs/golden-path/plugins/frontend/__meta__.md @@ -0,0 +1,34 @@ + + +# Sections + +## Creating your first plugin + +### Scaffolding a new plugin + +Talk through how to run the `backstage-cli create` command as well as what the output it creates is. This should touch on why we install this into `packages/app`. + +### Debugging + +How to handle common errors. + +## First steps with the new plugin + +### Creating a todo plugin + +We're going to be creating the frontend for a todo list plugin. We want the user to be able to create todos for themselves and show the user their current list of todos. + +To start, we'll use a list of mocked data. + +### Controlling your component dynamically + +Update the mocked data to be controlled by config. + +### HTTP API + +We want our todo plugin to reach the backend that we implemented in [the backend plugin Golden Path](../backend/001-first-steps.md). Let's write a client to do this (or use OpenAPI to generate a client for us). + +### Testing + +Unit tests - Let's write a unit test using React Testing Library to make sure that everything is working as expected. +Integration tests - Let's write an integration test using Playwright to _really_ make sure everything is working. diff --git a/docs/golden-path/plugins/integrations/001-catalog.md b/docs/golden-path/plugins/integrations/001-catalog.md new file mode 100644 index 0000000000..f5ed04116e --- /dev/null +++ b/docs/golden-path/plugins/integrations/001-catalog.md @@ -0,0 +1,23 @@ +--- +id: catalog +sidebar_label: 001 - Catalog +title: Integrating with Catalog +--- + +## Software Catalog + +### What is the Software Catalog? + + + +### Integration Points + + + +## Adding a new `backstage.io/todo` annotation + + + +## Custom TODO Entity Kind + + diff --git a/docs/golden-path/plugins/integrations/002-search.md b/docs/golden-path/plugins/integrations/002-search.md new file mode 100644 index 0000000000..b0ef762f27 --- /dev/null +++ b/docs/golden-path/plugins/integrations/002-search.md @@ -0,0 +1,19 @@ +--- +id: search +sidebar_label: 002 - Search +title: Integrating with Search +--- + +## Search + +### What is Backstage Search? + + + +### Common integration points + + + +## Creating a custom TODO collator + + diff --git a/docs/golden-path/plugins/integrations/003-permissions.md b/docs/golden-path/plugins/integrations/003-permissions.md new file mode 100644 index 0000000000..167d40d47f --- /dev/null +++ b/docs/golden-path/plugins/integrations/003-permissions.md @@ -0,0 +1,23 @@ +--- +id: permissions +sidebar_label: 003 - Permissions +title: Integrating with the Permission framework +--- + +## Permissions + +### What is the Permissions framework? + + + +### Common integration points + + + +## Creating private TODOs + + + +## Restricting who can create TODOs + + diff --git a/docs/golden-path/plugins/integrations/004-notifications.md b/docs/golden-path/plugins/integrations/004-notifications.md new file mode 100644 index 0000000000..23c44b4721 --- /dev/null +++ b/docs/golden-path/plugins/integrations/004-notifications.md @@ -0,0 +1,23 @@ +--- +id: notifications +sidebar_label: 004 - Notifications +title: Integrating with Notifications +--- + +## Notifications + +### What are Backstage Notifications? + + + +### Common integration points + + + +## TODO with an alarm + + + +## Create TODOs for other people and notify them + +