From 6ec07d6aa16d854f0216caa80314e1f679a9d820 Mon Sep 17 00:00:00 2001 From: Waldir Date: Mon, 18 Mar 2024 14:39:55 -0500 Subject: [PATCH 001/360] BEP 0006 Describe personas and separate portal and framework docs Signed-off-by: Waldir --- .../README.md | 240 ++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 beps/0006-docs-personas-framework-portal/README.md diff --git a/beps/0006-docs-personas-framework-portal/README.md b/beps/0006-docs-personas-framework-portal/README.md new file mode 100644 index 0000000000..96f9a5944a --- /dev/null +++ b/beps/0006-docs-personas-framework-portal/README.md @@ -0,0 +1,240 @@ +--- +title: Restructuring Backstage Documentation for Improved Navigation and Clarity +status: provisional +authors: + - '@waldirmontoya25' +owners: +project-areas: + - Documentation +creation-date: 2024-03-18 +--- + +# BEP: Enhancing Backstage Documentation: Personas, Framework, and Developer Portal + +[**Discussion Issue**](https://github.com/backstage/backstage/issues/23689) + +- [BEP: Enhancing Backstage Documentation: Personas, Framework, and Developer Portal](#bep-enhancing-backstage-documentation-personas-framework-and-developer-portal) + - [Summary](#summary) + - [Motivation](#motivation) + - [Goals](#goals) + - [Non-Goals](#non-goals) + - [Proposal](#proposal) + - [Design Details](#design-details) + - [Release Plan](#release-plan) + - [Dependencies](#dependencies) + - [Example Table of Contents](#example-table-of-contents) + +## Summary + +This BEP proposes restructuring the Backstage documentation to emphasize the dual nature of Backstage as both a framework for building developer portals and a fully functional developer portal out of the box, as demonstrated by the demo site. The documentation will be divided into two main sections: One focusing on the developer portal that users get with the core plugins, and another on the framework that allows integrators and builders to create their own developer portal. The goal is to improve clarity, navigation, and adoption of Backstage by positioning it as both a ready-to-use developer portal and a framework for building custom developer portals. + +## Motivation + +The current Backstage documentation has been reported to be difficult to navigate, making it challenging for different personas across the DevEx ecosystem to extract value. The CNCF [**assessment**](https://github.com/cncf/techdocs/tree/main/assessments/0008-backstage/) and the resulting [**issues**](https://github.com/backstage/backstage/issues/21893) highlight the need for improvement in the documentation structure. + +### Goals + +- Divide the documentation into two section: Framework and Developer Portal +- Define the personas Backstage is targeting +- Structure the documentation to cater the different personas +- Move the existing content to the appropriate section + +### Non-Goals + +- Rewrite the entire documentation from scratch +- Write additional content beyond the scope of the existing documentation + +## Proposal + +The proposed restructuring of the Backstage documentation revolves around two core ideas: + +1. Positioning Backstage as both a framework to build developer portals and a developer portal itself, and splitting the documentation into two main sections: + + - Developer Portal: Focusing on the features, configuration, and usage of the developer portal that users get out of the box with the core plugins. + - Framework: Covering the aspects of Backstage as a framework, including guides for integrators and builders who want to create their own developer portal using Backstage. + +2. Defining the personas participating in Backstage adoption journeys to improve documentation navigation. The identified personas are: + + - **User**: A person who uses Backstage to find information, use plugins, and consume the developer portal. + - **Administrator/Operator**: A person who configures, secures, and deploys the developer portal, manages plugins, and oversees the general administration of the developer portal. + - **Integrator/Builder**: A person who builds plugins, customizes the code and design, and creates custom-built developer portals based on the Backstage framework. This includes developers and designers and anyone adding new functionality to their own Backstage instance. + - **Product Manager/Business stakeholders**: A person who defines the strategy for adopting Backstage, identifies use cases, communicates the value proposition for adopting Backstage and connects the developer portal to the business strategy. + - **Contributor**: A person who contributes to the Backstage upstream ecosystem. + +The adoption strategy would be as follows: + +- Create a dedicated page describing the personas Backstage is targeting and the documentation sections that cater to each persona. +- Restructure the documentation into the two new sections (Framework and Developer Portal) and redistribute the existing content accordingly. +- Publish a blog post announcing the changes, highlighting Backstage's positioning as both a framework and a developer portal, and explaining the benefits of the restructured documentation. + +The benefits of restructuring the documentation according to these ideas include: + +1. Easier navigation and discoverability of information for different personas and use cases. +2. Clear separation of runtime and development documentation. +3. Simplified process for contributors to determine the appropriate location for new documentation. +4. Streamlined Backstage adoption process for new adopters. + +## Design Details + +- The Docs section of the microsite will be divided into two top-level sections: Framework and Developer Portal. +- The structure of the Table of Contents will align with the outline proposed in https://github.com/backstage/backstage/issues/21946. + +## Release Plan + +- Release the BEP by 03/24/2024. +- Discuss the changes with the community and gather feedback by 04/24/2024. +- Implement the changes by 04/30/2024. + +## Dependencies + +None + +## Example Table of Contents + +- Overview + - What is Backstage? + - Roadmap + - Vision + - Release and Versioning Policy + - Backstage Threat Model + - Logo assets + - Support and community +- Framework + - Architecture Overview + - Getting Started + - Integrator/Builder Guides + - Local Development + - CLI + - Linking in local packages + - Debugging Backstage + - Backstage core framework + - Systems + - Frontend + - Old + - New + - Backend + - Old + - New + - API Reference + - Tutorials + - Building plugins + - Intro to plugins + - Existing plugins + - Creating a new plugin + - Plugin development + - Structuring a plugin + - Integrating with other systems + - Integrating with the Catalog + - Integrating Search + - Composability system + - Internationalization + - Plugin analytics + - Feature flags + - OpenAPI + - Backends and APIs + - Testing + - Publishing + - Home Page + - Customizing the home page + - Software Catalog + - Extending the model + - External integrations + - Catalog Customization + - API + - Software Templates + - Writing custom actions + - Writing tests for actions + - Writing custom field extensions + - Writing custom step layouts + - Authorizing parameters, steps and actions + - Migrating to react-jsonschema-form@v5 + - Migrating to v1beta3 templates + - Search + - Overview + - Getting Started with search + - Search concepts + - Search architecture + - Search Engines + - How to Guides + - TechDocs + - Customizing TechDocs + - TechDocs add-ons + - Kubernetes + - Customizing the kubernetes plugin + - Authentication + - Proxy + - Permissions + - Overview + - Concepts + - Getting Started + - Writing a permission policy + - Frontend integration + - Defining custom permission rules + - Using permissions in plugins + - Designing for Backstage + - ADRs + - Accessibility + - References + - Contributor Guides + - Contributing to Backstage + - Reference +- Developer Portal + - Architecture Overview + - Getting Started + - Administrator Guides + - Developer Portal + - Installing and Configuring + - Database + - Authentication + - Installing plugins + - Customize the design + - Securing + - Deploying in Production + - Integrating with other systems + - Managing + - Monitoring + - Troubleshooting + - Upgrading + - Keeping backstage up to date + - Customizing + - Home Page + - Installing and Configuring + - Software Catalog + - Overview + - The life of an Entity + - Catalog Configuration + - System Model + - YAML file format + - Entity Reference + - Well Known annotations + - Well known relations + - Well known statuses + - Creating the catalog graph + - Software Templates + - Overview + - Configuring + - Adding a new template + - Writing a template + - Built in actions + - TechDocs + - Overview + - Getting Started + - Architecture + - Installing and configuring + - Using Cloud Storage for TechDocs generated files + - Configuring CI/CD to generate and publish TechDocs sites + - TechDocs CLI + - Troubleshooting + - Kubernetes + - Installing and Configuring + - Authentication + - Troubleshooting + - Search + - Product Manager Guides + - Strategies for adopting + - Use cases + - User Guides + - Logging in + - Registering a component + - Creating a new component + - Reference From 9a46050fa558b8abc7f1d726c904eb9fee82b296 Mon Sep 17 00:00:00 2001 From: aramissennyeydd Date: Tue, 19 Mar 2024 09:30:03 +0100 Subject: [PATCH 002/360] possible updates Signed-off-by: aramissennyeydd --- .../README.md | 196 +++++++++++------- 1 file changed, 122 insertions(+), 74 deletions(-) diff --git a/beps/0006-docs-personas-framework-portal/README.md b/beps/0006-docs-personas-framework-portal/README.md index 96f9a5944a..e79d6b11a7 100644 --- a/beps/0006-docs-personas-framework-portal/README.md +++ b/beps/0006-docs-personas-framework-portal/README.md @@ -79,6 +79,41 @@ The benefits of restructuring the documentation according to these ideas include - The Docs section of the microsite will be divided into two top-level sections: Framework and Developer Portal. - The structure of the Table of Contents will align with the outline proposed in https://github.com/backstage/backstage/issues/21946. +### User Persona + +Documentation written for the user persona should be high level, assuming little to no technical knowledge. Concepts like the difference between Backstage Framework and Developer Portal should be explained at a high level to give Users a working knowledge, but should not be flushed out completely until we identify the user as a distinct user persona. Users may also be Administrators, Integrators or Product Managers, but documentation for Users should make no assumptions on that. + +Example explanation of Backstage Framework vs Developer Portal: +"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. Backstage Framework provides the tools you need to build your own developer portal and Backstage Developer Portal is your custom developer portal built using the Backstage Framework." + +### Administrator Persona + +Documentation written for this persona should be DevOps technical, assuming a strong DevOps background with the exception of a Getting Started section. While we should assume an overall technical knowledge, where possible we should link out to existing strong guides for the technologies we use, ex: PostgreSQL, Docker, Kubernetes, etc. The goal with administrator documentation is to give administrators a strong understanding of how to deploy and manage a Backstage Developer Portal, best practices, and possible tripping points. + +Example explanation of Backstage Framework vs Developer Portal: +"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. As an administrator, you will be interacting with Backstage Developer Portal primarily -- this is the running Backstage instance that you're managing. It is also useful to have a high level understanding of the Backstage Framework for mitigating issues or better understanding how to scale your Backstage Developer Portal." + +### Integrator Persona + +Documentation written for this persona should be software technical, assuming a strong software background with the exception of a Getting Started section. While we can assume an overall technical knowledge, where possible we should link out to useful guides for the technologies we use, ex: Node.js, express.js, React, etc. The goal with documentation written for integrators is to give them a strong understanding of where their work fits into their company's Backstage Developer Portal, orient them to get support from the open source community, and prepare them for continuing to deliver value for their Backstage Developer Portal. + +Example explanation of Backstage Framework vs Developer Portal: +"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. As an integrator, most of your time will be spent working to deliver value on top of the Backstage Framework for your company's Backstage Developer Portal. This means creating plugins, theming your Backstage Developer Portal or adding integrations to internal data stores. You should have a strong understanding of the Backstage Framework and have a strong understaing of code that sits in your Backstage Developer Portal." + +### Business Stakeholder + +Documentation written for this persona should be strategic, assuming a strong background in business development and strategy. The goal for business documentation is to give a strong understanding of what Backstage Developer Portal can do for their company, how to deliver value quickly and continuously and guides for pitching or driving Backstage adoption. + +Example explanation of Backstage Framework vs Developer Portal: +"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. As a business stakeholder, your time should be spent with your company's Backstage Developer Portal solely. This means understanding the value proposition of an IDP, what improving the developer experience at your company means and what a successful Backstage Developer Portal looks like. The Backstage Framework is the technical underpinning and will generally be invisible to you." + +## Contributor + +Documentation written for this role should be technical, but should make no assumptions on technical strength. The goal with this documentation is to onboard new contributors to the technical stack and layout of the project, setting expectations for how to write code, documentation or generally contribute to the library. + +Example explanation of Backstage Framework vs Developer Portal: +"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. You will work with both the Backstage Framework and Backstage Developer Portal. Backstage Framework is the technical framework for Backstage Developer Portal. The Backstage Developer Portal is the end user for your plugins, documentation or other contributions. As a contributor, you will be working to influence either the Backstage Framework or plugins and Backstage Developer Portals across the world may use your contributions." + ## Release Plan - Release the BEP by 03/24/2024. @@ -92,6 +127,7 @@ None ## Example Table of Contents - Overview + - "The overview should introduce users to the concept of Backstage, what an IDP is, how to deliver value, why you should care about DevEx, etc." - What is Backstage? - Roadmap - Vision @@ -101,13 +137,16 @@ None - Support and community - Framework - Architecture Overview + - "The arch overview should explain how the framework is structured, where plugins and instances fit in and how to understand the current design of Backstage." - Getting Started - Integrator/Builder Guides - Local Development + - "Prepare users for how to develop locally, debug problems, run tests, etc." - CLI - Linking in local packages - Debugging Backstage - Backstage core framework + - "Internal documentation." - Systems - Frontend - Old @@ -116,8 +155,9 @@ None - Old - New - API Reference - - Tutorials + - "Internal documentation" - Building plugins + - "How to build a plugin, how to integrate it with other plugins, how to deploy and monitor it, and how to iterate on plugin development." - Intro to plugins - Existing plugins - Creating a new plugin @@ -134,48 +174,51 @@ None - Backends and APIs - Testing - Publishing - - Home Page - - Customizing the home page - - Software Catalog - - Extending the model - - External integrations - - Catalog Customization - - API - - Software Templates - - Writing custom actions - - Writing tests for actions - - Writing custom field extensions - - Writing custom step layouts - - Authorizing parameters, steps and actions - - Migrating to react-jsonschema-form@v5 - - Migrating to v1beta3 templates - - Search - - Overview - - Getting Started with search - - Search concepts - - Search architecture - - Search Engines - - How to Guides - - TechDocs - - Customizing TechDocs - - TechDocs add-ons - - Kubernetes - - Customizing the kubernetes plugin - - Authentication - - Proxy - - Permissions - - Overview - - Concepts - - Getting Started - - Writing a permission policy - - Frontend integration - - Defining custom permission rules - - Using permissions in plugins - - Designing for Backstage - - ADRs - - Accessibility - - References + - Core Plugins + - "How to leverage the existing plugins for your new plugin or customization options." + - Home Page + - Customizing the home page + - Software Catalog + - Extending the model + - External integrations + - Catalog Customization + - API + - Software Templates + - Writing custom actions + - Writing tests for actions + - Writing custom field extensions + - Writing custom step layouts + - Authorizing parameters, steps and actions + - Migrating to react-jsonschema-form@v5 + - Migrating to v1beta3 templates + - Search + - Overview + - Getting Started with search + - Search concepts + - Search architecture + - Search Engines + - How to Guides + - TechDocs + - Customizing TechDocs + - TechDocs add-ons + - Kubernetes + - Customizing the kubernetes plugin + - Authentication + - Proxy + - Permissions + - Overview + - Concepts + - Getting Started + - Writing a permission policy + - Frontend integration + - Defining custom permission rules + - Using permissions in plugins + - Designing for Backstage + - ADRs + - Accessibility + - References - Contributor Guides + - "How to get started contributing to OSS." - Contributing to Backstage - Reference - Developer Portal @@ -183,6 +226,7 @@ None - Getting Started - Administrator Guides - Developer Portal + - "How do I deploy, monitor, configure and verify my Backstage Developer Portal?" - Installing and Configuring - Database - Authentication @@ -197,43 +241,47 @@ None - Upgrading - Keeping backstage up to date - Customizing - - Home Page - - Installing and Configuring - - Software Catalog - - Overview - - The life of an Entity - - Catalog Configuration - - System Model - - YAML file format - - Entity Reference - - Well Known annotations - - Well known relations - - Well known statuses - - Creating the catalog graph - - Software Templates - - Overview - - Configuring - - Adding a new template - - Writing a template - - Built in actions - - TechDocs - - Overview - - Getting Started - - Architecture - - Installing and configuring - - Using Cloud Storage for TechDocs generated files - - Configuring CI/CD to generate and publish TechDocs sites - - TechDocs CLI + - Core Plugins + - "How do I install and configure Backstage Developer Portal with plugins." + - Home Page + - Installing and Configuring + - Software Catalog + - Overview + - The life of an Entity + - Catalog Configuration + - System Model + - YAML file format + - Entity Reference + - Well Known annotations + - Well known relations + - Well known statuses + - Creating the catalog graph + - Software Templates + - Overview + - Configuring + - Adding a new template + - Writing a template + - Built in actions + - TechDocs + - Overview + - Getting Started + - Architecture + - Installing and configuring + - Using Cloud Storage for TechDocs generated files + - Configuring CI/CD to generate and publish TechDocs sites + - TechDocs CLI + - Troubleshooting + - Kubernetes + - Installing and Configuring + - Authentication - Troubleshooting - - Kubernetes - - Installing and Configuring - - Authentication - - Troubleshooting - - Search + - Search - Product Manager Guides + - "How do I present Backstage to leadership, what are the benefits, why should I care, etc." - Strategies for adopting - Use cases - User Guides + - "How do I use the default OSS Backstage" - Logging in - Registering a component - Creating a new component From 596dea12617cdec16f7c1b4467a012607823bf58 Mon Sep 17 00:00:00 2001 From: Waldir Montoya Date: Wed, 20 Mar 2024 12:21:20 -0500 Subject: [PATCH 003/360] change BEP number and enhanced Persona description Signed-off-by: Waldir Montoya --- .../README.md | 101 ++++++++++++++---- 1 file changed, 80 insertions(+), 21 deletions(-) rename beps/{0006-docs-personas-framework-portal => 0007-docs-personas-framework-portal}/README.md (67%) diff --git a/beps/0006-docs-personas-framework-portal/README.md b/beps/0007-docs-personas-framework-portal/README.md similarity index 67% rename from beps/0006-docs-personas-framework-portal/README.md rename to beps/0007-docs-personas-framework-portal/README.md index e79d6b11a7..b18e4896ec 100644 --- a/beps/0006-docs-personas-framework-portal/README.md +++ b/beps/0007-docs-personas-framework-portal/README.md @@ -1,8 +1,9 @@ --- -title: Restructuring Backstage Documentation for Improved Navigation and Clarity +title: Enhancing Backstage Documentation, Personas, Framework, and Developer Portal status: provisional authors: - '@waldirmontoya25' + - '@aramissennyeyd' owners: project-areas: - Documentation @@ -20,6 +21,17 @@ creation-date: 2024-03-18 - [Non-Goals](#non-goals) - [Proposal](#proposal) - [Design Details](#design-details) + - [Personas](#personas) + - [User](#user) + - [Documentation Style](#documentation-style) + - [Administrator](#administrator) + - [Documentation Style](#documentation-style-1) + - [Integrator](#integrator) + - [Documentation Style](#documentation-style-2) + - [Contributor](#contributor) + - [Documentation Style](#documentation-style-3) + - [Business Stakeholder](#business-stakeholder) + - [Documentation Style](#documentation-style-4) - [Release Plan](#release-plan) - [Dependencies](#dependencies) - [Example Table of Contents](#example-table-of-contents) @@ -79,40 +91,87 @@ The benefits of restructuring the documentation according to these ideas include - The Docs section of the microsite will be divided into two top-level sections: Framework and Developer Portal. - The structure of the Table of Contents will align with the outline proposed in https://github.com/backstage/backstage/issues/21946. -### User Persona +### Personas -Documentation written for the user persona should be high level, assuming little to no technical knowledge. Concepts like the difference between Backstage Framework and Developer Portal should be explained at a high level to give Users a working knowledge, but should not be flushed out completely until we identify the user as a distinct user persona. Users may also be Administrators, Integrators or Product Managers, but documentation for Users should make no assumptions on that. +#### User -Example explanation of Backstage Framework vs Developer Portal: -"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. Backstage Framework provides the tools you need to build your own developer portal and Backstage Developer Portal is your custom developer portal built using the Backstage Framework." +Users navigate the developer portal to access tools, information, and plugins essential for their daily tasks. They rely on Backstage to effortlessly find resources, utilize integrations, and connect with other tools and services within their ecosystem. Their interaction is predominantly with the frontend of the portal, where ease of use, accessibility, and relevant content discovery are critical. -### Administrator Persona +##### Documentation Style -Documentation written for this persona should be DevOps technical, assuming a strong DevOps background with the exception of a Getting Started section. While we should assume an overall technical knowledge, where possible we should link out to existing strong guides for the technologies we use, ex: PostgreSQL, Docker, Kubernetes, etc. The goal with administrator documentation is to give administrators a strong understanding of how to deploy and manage a Backstage Developer Portal, best practices, and possible tripping points. +Documentation for this persona should be about usability of the portal once it is running. For example: -Example explanation of Backstage Framework vs Developer Portal: -"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. As an administrator, you will be interacting with Backstage Developer Portal primarily -- this is the running Backstage instance that you're managing. It is also useful to have a high level understanding of the Backstage Framework for mitigating issues or better understanding how to scale your Backstage Developer Portal." +- Understanding the mechanics of the Software Catalog +- Registering components +- Deleting components +- How the source of truth is the external tool linked through the plugins +- Understand dependencies relations and the overall schema of the catalog +- Using available scaffolder actions +- Customizing new workflows with available actions +- Searching +- Using available plugins +- Step by step tutorials -### Integrator Persona +#### Administrator -Documentation written for this persona should be software technical, assuming a strong software background with the exception of a Getting Started section. While we can assume an overall technical knowledge, where possible we should link out to useful guides for the technologies we use, ex: Node.js, express.js, React, etc. The goal with documentation written for integrators is to give them a strong understanding of where their work fits into their company's Backstage Developer Portal, orient them to get support from the open source community, and prepare them for continuing to deliver value for their Backstage Developer Portal. +Administrators are responsible for the behind-the-scenes technical setup and maintenance of the Backstage portal. This includes deploying the portal, configuring plugins, managing user access, and ensuring the security and performance of the system. They interact with both the frontend and backend, often using command-line tools, administrative dashboards, and configuration files to perform their tasks. -Example explanation of Backstage Framework vs Developer Portal: -"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. As an integrator, most of your time will be spent working to deliver value on top of the Backstage Framework for your company's Backstage Developer Portal. This means creating plugins, theming your Backstage Developer Portal or adding integrations to internal data stores. You should have a strong understanding of the Backstage Framework and have a strong understaing of code that sits in your Backstage Developer Portal." +##### Documentation Style -### Business Stakeholder +Documentation written for this persona should be DevOps technical, assuming a strong DevOps background. The goal with administrator documentation is to give administrators a strong understanding of how to deploy and manage a Backstage Developer Portal, best practices. For example: -Documentation written for this persona should be strategic, assuming a strong background in business development and strategy. The goal for business documentation is to give a strong understanding of what Backstage Developer Portal can do for their company, how to deliver value quickly and continuously and guides for pitching or driving Backstage adoption. +- Installing and upgrading +- Configuring + - Authentication + - Plugins +- Ingesting data (users/groups/components, etc) +- Installing plugins +- Implement Git Flows for the Developer portal +- Creating Pipelines for Docs generation +- Troubleshooting -Example explanation of Backstage Framework vs Developer Portal: -"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. As a business stakeholder, your time should be spent with your company's Backstage Developer Portal solely. This means understanding the value proposition of an IDP, what improving the developer experience at your company means and what a successful Backstage Developer Portal looks like. The Backstage Framework is the technical underpinning and will generally be invisible to you." +#### Integrator -## Contributor +Integrators actively work on extending and customizing Backstage. This includes developing new plugins, customizing the UI/UX, and integrating external services or data sources. Their work is deeply technical, involving coding, and engaging with the Backstage community for support and collaboration. They need a deep understanding of the Backstage architecture and APIs, working closely with both the framework's backend and frontend aspects. -Documentation written for this role should be technical, but should make no assumptions on technical strength. The goal with this documentation is to onboard new contributors to the technical stack and layout of the project, setting expectations for how to write code, documentation or generally contribute to the library. +##### Documentation Style -Example explanation of Backstage Framework vs Developer Portal: -"Backstage has two meanings, the Backstage Framework and the Backstage Developer Portal. You will work with both the Backstage Framework and Backstage Developer Portal. Backstage Framework is the technical framework for Backstage Developer Portal. The Backstage Developer Portal is the end user for your plugins, documentation or other contributions. As a contributor, you will be working to influence either the Backstage Framework or plugins and Backstage Developer Portals across the world may use your contributions." +Documentation written for this persona should be software technical, assuming a strong software background. While we can assume an overall technical knowledge, where possible we should link out to useful guides for the technologies we use, ex: Node.js, express.js, React, etc. The goal with documentation written for integrators is to give them a strong understanding of how to use the Backstage framework to build/evolve a company's Backstage Developer Portal, orient them to get support from the open source community, and prepare them for continuing to deliver value for their Backstage Developer Portal. For example: + +- API references +- Frontend and Backend systems +- Package architecture +- Extending the Software Catalog +- Creating custom themes +- Integrating new react components +- Building custom authentication providers/strategies +- Accessibility + +#### Contributor + +Contributors are involved in the development of the Backstage framework itself. They contribute to the core codebase, develop new features, fix bugs, create documentation and maintain the overall health of the project. They are deeply involved in the open-source community, collaborating with maintainers and other contributors to improve the framework and its ecosystem. + +##### Documentation Style + +The goal with documentation written for contributors is to give them a strong understanding of how to contribute to the Backstage framework, orient them to get support from the open source community, and prepare them for continuing to deliver value for the Backstage framework. For example: + +- Contributing to the Backstage framework +- Setting up a development environment +- Writing tests +- Writing documentation + +#### Business Stakeholder + +Business stakeholders use Backstage to align technical capabilities with business goals, monitoring how features and plugins support operational efficiency, developer satisfaction, and strategic objectives. They are involved in defining the strategy and measuring the impact of the developer portal on the organization. They need to navigate through dashboards, reports, and analytics within Backstage to gather insights and make informed decisions. + +##### Documentation Style + +Documentation written for this persona should be strategic, assuming a strong background in business development and strategy. The goal for business documentation is to give a strong understanding of what Backstage Developer Portal can do for their company, how to deliver value quickly and continuously and guides for pitching or driving Backstage adoption. For example: + +- Adoption use cases +- Adoption strategies +- Measuring success +- Case studies ## Release Plan From d779e3b055d8669a77729ba1bc15d61ad132e870 Mon Sep 17 00:00:00 2001 From: npiyush97 Date: Sun, 31 Mar 2024 11:46:02 +0530 Subject: [PATCH 004/360] fix not to add git commit link in about card edit button Signed-off-by: npiyush97 --- .changeset/thirty-plums-shout.md | 5 ++ .../AnnotateLocationEntityProcessor.test.ts | 48 +++++++++++++++++++ .../core/AnnotateLocationEntityProcessor.ts | 6 ++- 3 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 .changeset/thirty-plums-shout.md diff --git a/.changeset/thirty-plums-shout.md b/.changeset/thirty-plums-shout.md new file mode 100644 index 0000000000..5b5ffad6a9 --- /dev/null +++ b/.changeset/thirty-plums-shout.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +Added a regex test to check commit hash.If url is from git commit branch ignore the edit url. diff --git a/plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.test.ts b/plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.test.ts index 66b6300df9..2656de1c7b 100644 --- a/plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.test.ts +++ b/plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.test.ts @@ -166,5 +166,53 @@ describe('AnnotateLocationEntityProcessor', () => { }, }); }); + it('should not render edit button in about for invalid or git hash commit branch', async () => { + const entity: Entity = { + apiVersion: 'backstage.io/v1alpha1', + kind: 'Component', + metadata: { + name: 'my-component', + }, + }; + + const location: LocationSpec = { + type: 'url', + target: + 'https://github.com/backstage/backstage/blob/f1ba2bc6097a757c2827ff97fa301cff626de137/packages/app/catalog-info.yaml', + }; + const originLocation: LocationSpec = { + type: 'url', + target: + 'https://github.com/backstage/backstage/blob/f1ba2bc6097a757c2827ff97fa301cff626de137/catalog-info.yaml', + }; + + const integrations = ScmIntegrations.fromConfig(new ConfigReader({})); + const processor = new AnnotateLocationEntityProcessor({ integrations }); + + expect( + await processor.preProcessEntity( + entity, + location, + () => {}, + originLocation, + ), + ).toEqual({ + apiVersion: 'backstage.io/v1alpha1', + kind: 'Component', + metadata: { + name: 'my-component', + annotations: { + 'backstage.io/managed-by-location': + 'url:https://github.com/backstage/backstage/blob/f1ba2bc6097a757c2827ff97fa301cff626de137/packages/app/catalog-info.yaml', + 'backstage.io/managed-by-origin-location': + 'url:https://github.com/backstage/backstage/blob/f1ba2bc6097a757c2827ff97fa301cff626de137/catalog-info.yaml', + 'backstage.io/view-url': + 'https://github.com/backstage/backstage/blob/f1ba2bc6097a757c2827ff97fa301cff626de137/packages/app/catalog-info.yaml', + 'backstage.io/source-location': + 'url:https://github.com/backstage/backstage/tree/f1ba2bc6097a757c2827ff97fa301cff626de137/packages/app/', + }, + }, + }); + }); }); }); diff --git a/plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.ts b/plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.ts index d3329fa86c..1ff4963870 100644 --- a/plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.ts +++ b/plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.ts @@ -53,12 +53,16 @@ export class AnnotateLocationEntityProcessor implements CatalogProcessor { let viewUrl; let editUrl; let sourceLocation; + const gitCommitBranchURLPattern = /\b[0-9a-f]{5,40}\b/; if (location.type === 'url') { const scmIntegration = integrations.byUrl(location.target); viewUrl = location.target; - editUrl = scmIntegration?.resolveEditUrl(location.target); + + if (!gitCommitBranchURLPattern.test(location.target)) { + editUrl = scmIntegration?.resolveEditUrl(location.target); + } const sourceUrl = scmIntegration?.resolveUrl({ url: './', From 2eb7b4f1d61b66b346c7b4c71c84cb8c42b28b66 Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Sat, 13 Apr 2024 17:39:39 +0200 Subject: [PATCH 005/360] updating getting-started permissions docs to new backend Signed-off-by: Peter Macdonald --- docs/permissions/getting-started.md | 146 ++++++++++++---------------- 1 file changed, 60 insertions(+), 86 deletions(-) diff --git a/docs/permissions/getting-started.md b/docs/permissions/getting-started.md index e241f0e38e..de092dce01 100644 --- a/docs/permissions/getting-started.md +++ b/docs/permissions/getting-started.md @@ -20,20 +20,12 @@ The permissions framework depends on a few other Backstage systems, which must b The permissions framework itself is new to Backstage and still evolving quickly. To ensure your version of Backstage has all the latest permission-related functionality, it’s important to upgrade to the latest version. The [Backstage upgrade helper](https://backstage.github.io/upgrade-helper/) is a great tool to help ensure that you’ve made all the necessary changes during the upgrade! -### Enable service-to-service authentication - -Service-to-service authentication allows Backstage backend code to verify that a given request originates from elsewhere in the Backstage backend. This is useful for tasks like collation of catalog entities in the search index. This type of request shouldn’t be permissioned, so it’s important to configure this feature before trying to use the permissions framework. - -To set up service-to-service authentication, follow the [service-to-service authentication docs](../auth/service-to-service-auth.md). - ### Supply an identity resolver to populate group membership on sign in **Note**: If you are working off of an existing Backstage instance, you likely already have some form of an identity resolver set up. Like many other parts of Backstage, the permissions framework relies on information about group membership. This simplifies authoring policies through the use of groups, rather than requiring each user to be listed in the configuration. Group membership is also often useful for conditional permissions, for example allowing permissions to act on an entity to be granted when a user is a member of a group that owns that entity. -[The IdentityResolver docs](../auth/identity-resolver.md) describe the process for resolving group membership on sign in. - ## Optionally add cookie-based authentication Asset requests initiated by the browser will not include a token in the `Authorization` header. If these requests check authorization through the permission framework, as done in plugins like TechDocs, then you'll need to set up cookie-based authentication. Refer to the ["Authenticate API requests"](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/authenticate-api-requests.md) tutorial for a demonstration on how to implement this behavior. @@ -44,68 +36,32 @@ Asset requests initiated by the browser will not include a token in the `Authori The permissions framework uses a new `permission-backend` plugin to accept authorization requests from other plugins across your Backstage instance. The Backstage backend does not include this permission backend by default, so you will need to add it: -1. Add `@backstage/plugin-permission-backend` as a dependency of your Backstage backend: +1. Add `@backstage/plugin-permission-backend` and `@backstage/plugin-permission-backend-module-allow-all-policy` to your backend dependencies, this will add the permission backend and a policy that allows all permissions: ```bash # From your Backstage root directory yarn --cwd packages/backend add @backstage/plugin-permission-backend ``` -2. Add the following to a new file, `packages/backend/src/plugins/permission.ts`. This adds the permission-backend router, and configures it with a policy which allows everything. - - ```typescript title="packages/backend/src/plugins/permission.ts" - import { createRouter } from '@backstage/plugin-permission-backend'; - import { - AuthorizeResult, - PolicyDecision, - } from '@backstage/plugin-permission-common'; - import { PermissionPolicy } from '@backstage/plugin-permission-node'; - import { Router } from 'express'; - import { PluginEnvironment } from '../types'; - - class TestPermissionPolicy implements PermissionPolicy { - async handle(): Promise { - return { result: AuthorizeResult.ALLOW }; - } - } - - export default async function createPlugin( - env: PluginEnvironment, - ): Promise { - return await createRouter({ - config: env.config, - logger: env.logger, - discovery: env.discovery, - policy: new TestPermissionPolicy(), - identity: env.identity, - }); - } + ```bash + # From your Backstage root directory + yarn --cwd packages/backend add @backstage/plugin-permission-backend-module-allow-all-policy ``` -3. Wire up the permission policy in `packages/backend/src/index.ts`. [The index in the example backend](https://github.com/backstage/backstage/blob/master/packages/backend/src/index.ts) shows how to do this. You’ll need to import the module from the previous step, create a plugin environment, and add the router to the express app: +2. Add the following to `packages/backend/src/index.ts`. This adds the permission-backend router, and configures it with a policy which allows everything. - ```ts title="packages/backend/src/index.ts" - import proxy from './plugins/proxy'; - import techdocs from './plugins/techdocs'; - import search from './plugins/search'; + ```typescript title="packages/backend/src/index.ts" + import { createBackend } from '@backstage/backend-defaults'; + const backend = createBackend(); + // ... /* highlight-add-next-line */ - import permission from './plugins/permission'; - - async function main() { - const techdocsEnv = useHotMemoize(module, () => createEnv('techdocs')); - const searchEnv = useHotMemoize(module, () => createEnv('search')); - const appEnv = useHotMemoize(module, () => createEnv('app')); - /* highlight-add-next-line */ - const permissionEnv = useHotMemoize(module, () => createEnv('permission')); - // .. - - apiRouter.use('/techdocs', await techdocs(techdocsEnv)); - apiRouter.use('/proxy', await proxy(proxyEnv)); - apiRouter.use('/search', await search(searchEnv)); - /* highlight-add-next-line */ - apiRouter.use('/permission', await permission(permissionEnv)); - // .. - } + backend.add(import('@backstage/plugin-permission-backend/alpha')); + /* highlight-add-next-line */ + backend.add( + import('@backstage/plugin-permission-backend-module-allow-all-policy'), + ); + // ... + backend.start(); ``` ### 2. Enable and test the permissions system @@ -119,43 +75,61 @@ Now that the permission backend is running, it’s time to enable the permission enabled: true ``` -2. Update the PermissionPolicy in `packages/backend/src/plugins/permission.ts` to disable a permission that’s easy for us to test. This policy rejects any attempt to delete a catalog entity: +2. Its now all wired up and working, great! But perhaps we don't want to simply allow everything, lets try and create our own policy, to do this you can create a new folder in `packages/backend/src` called `permissions` and create a new file called `policy.ts`, in that file we can add the following to create a policy that denies deleting entities from the catalog: - ```ts title="packages/backend/src/plugins/permission.ts" - import { createRouter } from '@backstage/plugin-permission-backend'; + ```ts title="packages/backend/src/permissions/policy.ts" import { AuthorizeResult, PolicyDecision, } from '@backstage/plugin-permission-common'; - /* highlight-remove-next-line */ - import { PermissionPolicy } from '@backstage/plugin-permission-node'; - /* highlight-add-start */ import { PermissionPolicy, PolicyQuery, } from '@backstage/plugin-permission-node'; - /* highlight-add-end */ - import { Router } from 'express'; - import { PluginEnvironment } from '../types'; - - class TestPermissionPolicy implements PermissionPolicy { - /* highlight-remove-next-line */ - async handle(): Promise { - /* highlight-add-start */ - async handle(request: PolicyQuery): Promise { - if (request.permission.name === 'catalog.entity.delete') { - return { - result: AuthorizeResult.DENY, - }; - } - /* highlight-add-end */ - - return { result: AuthorizeResult.ALLOW }; - } - } ``` -3. Now that you’ve made this change, you should find that the unregister entity menu option on the catalog entity page is disabled. +export class DenyCatalogDeletePolicy implements PermissionPolicy { +async handle(request: PolicyQuery): Promise { +if (request.permission.name === 'catalog.entity.delete') { +return { +result: AuthorizeResult.DENY, +}; +} + + return { result: AuthorizeResult.ALLOW }; + } + +} + +```` +3. We then need to use the permissions backend policy extension point to register our policy, to do this we can add the following to `packages/backend/src/index.ts`: + +```ts title="packages/backend/src/index.ts" +import { createBackend } from '@backstage/backend-defaults'; +import { DenyCatalogDeletePolicy } from './permissions/policy'; +const backend = createBackend(); +// ... +backend.add(import('@backstage/plugin-permission-backend/alpha')); +/* highlight-remove-next-line */ +backend.add(import('@backstage/plugin-permission-backend-module-allow-all-policy')); + /* highlight-add-next-line */ + backend.add(createBackendModule({ + pluginId: 'permission', + moduleId: 'deny-catalog-delete-policy', + register(reg){ + reg.registerInit({ + deps: { policy: policyExtensionPoint }, + async init({ policy }) { + policy.setPolicy(new DenyCatalogDeletePolicy()); + } + }) + } +})); +// ... +backend.start(); +```` + +4. Now that you’ve made this change, you should find that the unregister entity menu option on the catalog entity page is disabled. ![Entity detail page showing disabled unregister entity context menu entry](../assets/permissions/disabled-unregister-entity.png) From 7246fba8ec04caf0bd693773cce2a16bb12416fb Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Mon, 15 Apr 2024 15:18:17 +0200 Subject: [PATCH 006/360] removes old youtube video Signed-off-by: Peter Macdonald --- docs/permissions/getting-started.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/permissions/getting-started.md b/docs/permissions/getting-started.md index de092dce01..bd4294caad 100644 --- a/docs/permissions/getting-started.md +++ b/docs/permissions/getting-started.md @@ -4,12 +4,6 @@ title: Getting Started description: How to get started with the permission framework as an integrator --- -If you prefer to watch a video instead, you can start with this video introduction: - - - -> Note: This video was recorded in the January 2022 Contributors Session using `@backstage/create-app@0.4.14`. Some aspects of the demo may have changed in later releases. - Backstage integrators control permissions by writing a policy. In general terms, a policy is simply an async function which receives a request to authorize a specific action for a user and (optional) resource, and returns a decision on whether to authorize that permission. Integrators can implement their own policies from scratch, or adopt reusable policies written by others. ## Prerequisites From cf3ec13839638d865fbfc186648fe207fc006c03 Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Mon, 15 Apr 2024 15:23:13 +0200 Subject: [PATCH 007/360] weird formatting fix Signed-off-by: Peter Macdonald --- docs/permissions/getting-started.md | 120 ++++++++++++++-------------- 1 file changed, 61 insertions(+), 59 deletions(-) diff --git a/docs/permissions/getting-started.md b/docs/permissions/getting-started.md index bd4294caad..ef2194a91c 100644 --- a/docs/permissions/getting-started.md +++ b/docs/permissions/getting-started.md @@ -32,31 +32,31 @@ The permissions framework uses a new `permission-backend` plugin to accept autho 1. Add `@backstage/plugin-permission-backend` and `@backstage/plugin-permission-backend-module-allow-all-policy` to your backend dependencies, this will add the permission backend and a policy that allows all permissions: - ```bash - # From your Backstage root directory - yarn --cwd packages/backend add @backstage/plugin-permission-backend - ``` +```bash +# From your Backstage root directory +yarn --cwd packages/backend add @backstage/plugin-permission-backend +``` - ```bash - # From your Backstage root directory - yarn --cwd packages/backend add @backstage/plugin-permission-backend-module-allow-all-policy - ``` +```bash +# From your Backstage root directory +yarn --cwd packages/backend add @backstage/plugin-permission-backend-module-allow-all-policy +``` 2. Add the following to `packages/backend/src/index.ts`. This adds the permission-backend router, and configures it with a policy which allows everything. - ```typescript title="packages/backend/src/index.ts" - import { createBackend } from '@backstage/backend-defaults'; - const backend = createBackend(); - // ... - /* highlight-add-next-line */ - backend.add(import('@backstage/plugin-permission-backend/alpha')); - /* highlight-add-next-line */ - backend.add( - import('@backstage/plugin-permission-backend-module-allow-all-policy'), - ); - // ... - backend.start(); - ``` +```typescript title="packages/backend/src/index.ts" +import { createBackend } from '@backstage/backend-defaults'; +const backend = createBackend(); +// ... +/* highlight-add-next-line */ +backend.add(import('@backstage/plugin-permission-backend/alpha')); +/* highlight-add-next-line */ +backend.add( + import('@backstage/plugin-permission-backend-module-allow-all-policy'), +); +// ... +backend.start(); +``` ### 2. Enable and test the permissions system @@ -64,38 +64,36 @@ Now that the permission backend is running, it’s time to enable the permission 1. Set the property `permission.enabled` to `true` in `app-config.yaml`. - ```yaml title="app-config.yaml" - permission: - enabled: true - ``` +```yaml title="app-config.yaml" +permission: + enabled: true +``` 2. Its now all wired up and working, great! But perhaps we don't want to simply allow everything, lets try and create our own policy, to do this you can create a new folder in `packages/backend/src` called `permissions` and create a new file called `policy.ts`, in that file we can add the following to create a policy that denies deleting entities from the catalog: - ```ts title="packages/backend/src/permissions/policy.ts" - import { - AuthorizeResult, - PolicyDecision, - } from '@backstage/plugin-permission-common'; - import { - PermissionPolicy, - PolicyQuery, - } from '@backstage/plugin-permission-node'; - ``` +```ts title="packages/backend/src/permissions/policy.ts" +import { + AuthorizeResult, + PolicyDecision, +} from '@backstage/plugin-permission-common'; +import { + PermissionPolicy, + PolicyQuery, +} from '@backstage/plugin-permission-node'; export class DenyCatalogDeletePolicy implements PermissionPolicy { -async handle(request: PolicyQuery): Promise { -if (request.permission.name === 'catalog.entity.delete') { -return { -result: AuthorizeResult.DENY, -}; -} - - return { result: AuthorizeResult.ALLOW }; + async handle(request: PolicyQuery): Promise { + if (request.permission.name === 'catalog.entity.delete') { + return { + result: AuthorizeResult.DENY, + }; } + return { result: AuthorizeResult.ALLOW }; + } } +``` -```` 3. We then need to use the permissions backend policy extension point to register our policy, to do this we can add the following to `packages/backend/src/index.ts`: ```ts title="packages/backend/src/index.ts" @@ -105,23 +103,27 @@ const backend = createBackend(); // ... backend.add(import('@backstage/plugin-permission-backend/alpha')); /* highlight-remove-next-line */ -backend.add(import('@backstage/plugin-permission-backend-module-allow-all-policy')); - /* highlight-add-next-line */ - backend.add(createBackendModule({ - pluginId: 'permission', - moduleId: 'deny-catalog-delete-policy', - register(reg){ - reg.registerInit({ - deps: { policy: policyExtensionPoint }, - async init({ policy }) { - policy.setPolicy(new DenyCatalogDeletePolicy()); - } - }) - } -})); +backend.add( + import('@backstage/plugin-permission-backend-module-allow-all-policy'), +); +/* highlight-add-next-line */ +backend.add( + createBackendModule({ + pluginId: 'permission', + moduleId: 'deny-catalog-delete-policy', + register(reg) { + reg.registerInit({ + deps: { policy: policyExtensionPoint }, + async init({ policy }) { + policy.setPolicy(new DenyCatalogDeletePolicy()); + }, + }); + }, + }), +); // ... backend.start(); -```` +``` 4. Now that you’ve made this change, you should find that the unregister entity menu option on the catalog entity page is disabled. From 7c1540d46ed22ca1980e0fa89640c72ca103d3a4 Mon Sep 17 00:00:00 2001 From: npiyush97 Date: Tue, 16 Apr 2024 15:09:22 +0530 Subject: [PATCH 008/360] checking url is sha1 hash of len 40 Signed-off-by: npiyush97 --- .../src/modules/core/AnnotateLocationEntityProcessor.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.ts b/plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.ts index 1ff4963870..83638d205f 100644 --- a/plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.ts +++ b/plugins/catalog-backend/src/modules/core/AnnotateLocationEntityProcessor.ts @@ -53,7 +53,7 @@ export class AnnotateLocationEntityProcessor implements CatalogProcessor { let viewUrl; let editUrl; let sourceLocation; - const gitCommitBranchURLPattern = /\b[0-9a-f]{5,40}\b/; + const gitCommitBranchURLPattern = /\b[0-9a-f]{40,}\b/; if (location.type === 'url') { const scmIntegration = integrations.byUrl(location.target); From 18f565273a1eb0d30e1b6fc0735ad5df985e2016 Mon Sep 17 00:00:00 2001 From: Peter Macdonald Date: Tue, 16 Apr 2024 20:15:35 +0200 Subject: [PATCH 009/360] fixing highlight line Signed-off-by: Peter Macdonald --- docs/permissions/getting-started.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/permissions/getting-started.md b/docs/permissions/getting-started.md index ef2194a91c..5f8db5556e 100644 --- a/docs/permissions/getting-started.md +++ b/docs/permissions/getting-started.md @@ -106,7 +106,7 @@ backend.add(import('@backstage/plugin-permission-backend/alpha')); backend.add( import('@backstage/plugin-permission-backend-module-allow-all-policy'), ); -/* highlight-add-next-line */ +/* highlight-add-start */ backend.add( createBackendModule({ pluginId: 'permission', @@ -121,6 +121,7 @@ backend.add( }, }), ); +/* highlight-add-end */ // ... backend.start(); ``` From 96cd13eca2ddc488a35f9bbb11ae7fdba29c22bf Mon Sep 17 00:00:00 2001 From: Benjamin Janssens Date: Tue, 23 Apr 2024 12:36:38 +0200 Subject: [PATCH 010/360] feat: add property ownerPickerMode to TechDocsIndexPage and DefaultApiExplorerPage Signed-off-by: Benjamin Janssens --- .changeset/gentle-baboons-peel.md | 5 +++++ .changeset/tiny-pandas-return.md | 5 +++++ plugins/api-docs/api-report.md | 2 ++ .../ApiExplorerPage/DefaultApiExplorerPage.tsx | 11 +++++++++-- plugins/techdocs/api-report.md | 2 ++ .../src/home/components/DefaultTechDocsHome.tsx | 4 ++-- .../src/home/components/TechDocsIndexPage.tsx | 6 +++++- 7 files changed, 30 insertions(+), 5 deletions(-) create mode 100644 .changeset/gentle-baboons-peel.md create mode 100644 .changeset/tiny-pandas-return.md diff --git a/.changeset/gentle-baboons-peel.md b/.changeset/gentle-baboons-peel.md new file mode 100644 index 0000000000..d63396860b --- /dev/null +++ b/.changeset/gentle-baboons-peel.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-techdocs': minor +--- + +Added property ownerPickerMode to TechDocsIndexPage diff --git a/.changeset/tiny-pandas-return.md b/.changeset/tiny-pandas-return.md new file mode 100644 index 0000000000..d584accccf --- /dev/null +++ b/.changeset/tiny-pandas-return.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-api-docs': patch +--- + +Added property ownerPickerMode to DefaultApiExplorerPage diff --git a/plugins/api-docs/api-report.md b/plugins/api-docs/api-report.md index 7523198298..2fc852777b 100644 --- a/plugins/api-docs/api-report.md +++ b/plugins/api-docs/api-report.md @@ -9,6 +9,7 @@ import { ApiEntity } from '@backstage/catalog-model'; import { ApiRef } from '@backstage/core-plugin-api'; import { BackstagePlugin } from '@backstage/core-plugin-api'; import { CatalogTableRow } from '@backstage/plugin-catalog'; +import { EntityOwnerPickerProps } from '@backstage/plugin-catalog-react'; import { ExternalRouteRef } from '@backstage/core-plugin-api'; import { InfoCardVariants } from '@backstage/core-components'; import { JSX as JSX_2 } from 'react'; @@ -105,6 +106,7 @@ export type DefaultApiExplorerPageProps = { initiallySelectedFilter?: UserListFilterKind; columns?: TableColumn[]; actions?: TableProps['actions']; + ownerPickerMode?: EntityOwnerPickerProps['mode']; }; // @public (undocumented) diff --git a/plugins/api-docs/src/components/ApiExplorerPage/DefaultApiExplorerPage.tsx b/plugins/api-docs/src/components/ApiExplorerPage/DefaultApiExplorerPage.tsx index dc83c2528d..6b5917c52d 100644 --- a/plugins/api-docs/src/components/ApiExplorerPage/DefaultApiExplorerPage.tsx +++ b/plugins/api-docs/src/components/ApiExplorerPage/DefaultApiExplorerPage.tsx @@ -35,6 +35,7 @@ import { UserListFilterKind, UserListPicker, CatalogFilterLayout, + EntityOwnerPickerProps, } from '@backstage/plugin-catalog-react'; import React from 'react'; import { registerComponentRouteRef } from '../../routes'; @@ -60,6 +61,7 @@ export type DefaultApiExplorerPageProps = { initiallySelectedFilter?: UserListFilterKind; columns?: TableColumn[]; actions?: TableProps['actions']; + ownerPickerMode?: EntityOwnerPickerProps['mode']; }; /** @@ -67,7 +69,12 @@ export type DefaultApiExplorerPageProps = { * @public */ export const DefaultApiExplorerPage = (props: DefaultApiExplorerPageProps) => { - const { initiallySelectedFilter = 'all', columns, actions } = props; + const { + initiallySelectedFilter = 'all', + columns, + actions, + ownerPickerMode, + } = props; const configApi = useApi(configApiRef); const generatedSubtitle = `${ @@ -101,7 +108,7 @@ export const DefaultApiExplorerPage = (props: DefaultApiExplorerPageProps) => {