diff --git a/docs/features/search/README.md b/docs/features/search/README.md index a151da1736..f1744d4d80 100644 --- a/docs/features/search/README.md +++ b/docs/features/search/README.md @@ -10,76 +10,23 @@ description: Backstage Search lets you find the right information you are lookin ## What is it? -Backstage Search lets you find the right information you are looking for in the -Backstage ecosystem. +Backstage Search lets you find the right information you are looking for in the Backstage ecosystem. ## Features -- A federated, faceted search, searching across all entities registered in your - Backstage instance. +- A federated, faceted search, searching across all entities registered in your Backstage instance. - A search that lets you plug in your own search engine of choice. -- A standardized search API where you can choose to index other plugins data. +- A standardized search API where you can choose to index data from other plugins. ## Project roadmap -| Version | Description | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Backstage Search Pre-Alpha ✅ | Search Frontend letting you search through the entities of the software catalog. [See Pre-Alpha Use Cases.](#backstage-search-pre-alpha) | -| Backstage Search Alpha ✅ | Basic “out-of-the-box” in-memory indexing process of entities, and their metadata, registered to the Software Catalog. [See Alpha Use Cases](#backstage-search-alpha). | -| Backstage Search Beta ✅ | At least one production-ready search engine that supports the same use-cases as in the alpha. [See Beta Use Cases](#backstage-search-beta). | -| [Backstage Search 1.0 ⌛] | A stable Search API for plugin developers to add search to their plugins, and app integrators to expose that to their users. [See 1.0 Use Cases](#backstage-search-1.0). | +### Now -## Use Cases +**Backstage Search 1.0** -#### Backstage Search Pre-Alpha - -The pre-alpha is intended to solve for the following user stories, but will get -there by means of a front-end only, non-extensible MVP. - -- As a software engineer I should be able to navigate to a search page and - search for entities registered in the Software Catalog. -- As a software engineer I should be able to use the search input field in the - sidebar to search for entities registered in the Software Catalog. -- As a software engineer I should be able to see the number of results my search - returned. -- As a software engineer I should be able to filter on metadata (kind, - lifecycle) when I’ve performed a search. -- As a software engineer I should be able to hide the filters if I don’t need to - use them. - -#### Backstage Search Alpha - -We will consider Backstage Search to be in alpha when the above use-cases are -met, but built on top of a flexible, extensible platform. - -- As an integrator, I should be able to provide all of the pre-alpha experiences - to my users if I choose, but also be able to customize the experience using a - composable set of components. -- As a plugin developer, I should have a standard way to expose my plugin's data - to Backstage Search. -- As an integrator, I should still be able to expose everything in the Software - Catalog in search, but it should be possible to customize what is searchable. -- As an integrator, although I should be able to customize all of the above, it - should be possible to have the pre-alpha user experiences covered without - having to set up and configure a search engine. - -#### Backstage Search Beta - -We will consider Backstage Search to be in a beta phase when the above use-cases -are met, and can be deployed using a production-ready search engine. - -- As an integrator, I should be able to power my Backstage Search experience - (including querying and indexing) using a production-ready search engine like - ElasticSearch. -- As an integrator, I should be able to configure the connection to my search - engine in `app_config.yaml`. -- As an integrator, I should be able to tune the queries sent to my chosen - search engine according to my organization's needs, but a sensible default - query should be in place so that I am not required to do so. - -#### Backstage Search 1.0 +A stable Search API for plugin developers to add search to their plugins, and app integrators to expose that to their users. We will consider Backstage Search to be 1.0 when the above use-cases are met, and an ecosystem of search-enabled plugins are available and @@ -92,9 +39,23 @@ stable. how to customize and extend search in my Backstage instance to meet my organization's needs. -more to come... +### Next -## Search Engines Supported +_Not specified_ + +### Someday/Maybe + +_Not specified_ + +### Done + +See [Done](#done) below for a list of completed roadmap items. + +## Supported + +The following sections show the search engines and plugins currently supported by Backstage Search. + +### Search engines See [Backstage Search Architecture](architecture.md) to get an overview of how the search engines are used. @@ -108,11 +69,11 @@ the search engines are used. [Reach out to us](#get-involved) if you want to chat about support for more search engines. -## Plugins Integrated with Search +### Plugins integrated with Backstage Search | Plugin | Support Status | | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | -| Catalog | ✅ | +| Software Catalog | ✅ | | [TechDocs](./how-to-guides.md#how-to-index-techdocs-documents) | ✅ | | [Stack Overflow](https://github.com/backstage/backstage/blob/master/plugins/stack-overflow-backend/README.md#index-stack-overflow-questions-to-search) | ✅ | @@ -131,8 +92,62 @@ plugins integrated to search. | Backend Plugin Module | @backstage/plugin-search-backend-module-elasticsearch | | Backend Plugin Module | @backstage/plugin-search-backend-module-pg | -## Get Involved +## Get involved For any questions, feedback, or to help move search forward, reach out to us in -the `#search` channel of our +the **#search** channel of our [Discord chatroom](https://github.com/backstage/backstage#community). + +## Done + +**Backstage Search Pre-Alpha** + +Search Frontend letting you search through the entities of the software catalog. + +The pre-alpha is intended to solve for the following user stories, but will get +there by means of a front-end only, non-extensible MVP. + +- As a software engineer I should be able to navigate to a search page and + search for entities registered in the Software Catalog. +- As a software engineer I should be able to use the search input field in the + sidebar to search for entities registered in the Software Catalog. +- As a software engineer I should be able to see the number of results my search + returned. +- As a software engineer I should be able to filter on metadata (kind, + lifecycle) when I’ve performed a search. +- As a software engineer I should be able to hide the filters if I don’t need to + use them. + +**Backstage Search Alpha** + +Basic “out-of-the-box” in-memory indexing process of entities, and their metadata, registered to the Software Catalog. + +We will consider Backstage Search to be in alpha when the above use-cases are +met, but built on top of a flexible, extensible platform. + +- As an integrator, I should be able to provide all of the pre-alpha experiences + to my users if I choose, but also be able to customize the experience using a + composable set of components. +- As a plugin developer, I should have a standard way to expose my plugin's data + to Backstage Search. +- As an integrator, I should still be able to expose everything in the Software + Catalog in search, but it should be possible to customize what is searchable. +- As an integrator, although I should be able to customize all of the above, it + should be possible to have the pre-alpha user experiences covered without + having to set up and configure a search engine. + +**Backstage Search Beta** + +At least one production-ready search engine that supports the same use-cases as in the alpha. + +We will consider Backstage Search to be in a beta phase when the above use-cases +are met, and can be deployed using a production-ready search engine. + +- As an integrator, I should be able to power my Backstage Search experience + (including querying and indexing) using a production-ready search engine like + ElasticSearch. +- As an integrator, I should be able to configure the connection to my search + engine in **app_config.yaml**. +- As an integrator, I should be able to tune the queries sent to my chosen + search engine according to my organization's needs, but a sensible default + query should be in place so that I am not required to do so. diff --git a/docs/features/techdocs/README.md b/docs/features/techdocs/README.md index 5ac275b8b4..48c469def7 100644 --- a/docs/features/techdocs/README.md +++ b/docs/features/techdocs/README.md @@ -21,14 +21,44 @@ Today, it is one of the core products in Spotify’s developer experience offeri - Deploy TechDocs no matter how your software environment is set up. - Discover your Service's technical documentation from the Service's page in Backstage Catalog. - Create documentation-only sites for any purpose by just writing Markdown. +- Take advantage of the [TechDocs Addon Framework](addons.md) to add features on top of the base docs-like-code experience. - Explore and take advantage of the large ecosystem of [MkDocs plugins](https://www.mkdocs.org/user-guide/plugins/) to create a rich reading experience. - Search for and find docs. -## Platforms supported +## Project roadmap -See [TechDocs Architecture](architecture.md) to get an overview of where these -providers are used. +### Now + +With the Backstage 1.2 release, we have introduced the [TechDocs Addon Framework](https://backstage.io/blog/2022/05/13/techdocs-addon-framework) for augmenting the TechDocs experience at read-time. + +In addition to the framework itself, we have open sourced a **ReportIssue** Addon, helping you to create a feedback loop that drives up documentation quality and foster a documentation culture at your organization. + +### Next + +What can we do in TechDocs to help drive up documentation quality? We have many ideas, for example, a Trust Card with associated Trust Score and automatic triggering of documentation maintenance notifications. + +### Someday/Maybe + +- Contribute to and deploy from a marketplace of TechDocs Addons +- Addon: MDX (allows you to use JSX in your Markdown content) +- Can we go static site generator agnostic? +- Better integration with + [Scaffolder V2](https://github.com/backstage/backstage/issues/2771) (e.g. easy to choose and apply documentation template with Software Templates) +- Possible to configure several aspects about TechDocs (e.g. URL, homepage, + theme) + +### Done + +See [Done](#done) below for a list of completed roadmap items. + +## Supported + +The following sections show the source code hosting providers and file storage providers that are currently supported by TechDocs. + +See [TechDocs Architecture](architecture.md) to get an overview of where the below providers are used. + +### Source code hosting providers | Source Code Hosting Provider | Support Status | | ---------------------------- | -------------- | @@ -39,6 +69,8 @@ providers are used. | GitLab | Yes ✅ | | GitLab Enterprise | Yes ✅ | +### File storage providers + | File Storage Provider | Support Status | | --------------------------------- | -------------- | | Local Filesystem of Backstage app | Yes ✅ | @@ -47,64 +79,17 @@ providers are used. | Azure Blob Storage | Yes ✅ | | OpenStack Swift | Community ✅ | -[Reach out to us](#feedback) if you want to request more platforms. - -## Project roadmap - -### **Published versions** - -**Alpha release** ✅ - -[Milestone](https://github.com/backstage/backstage/milestone/16) - -- Alpha of TechDocs that you can use end to end - and contribute to. - -**Beta release** ✅ - -[Milestone](https://github.com/backstage/backstage/milestone/29) - -- TechDocs' recommended setup supports most environments (CI systems, cloud - storage solutions, source control systems). -- [Instructions for upgrading from Alpha to Beta](how-to-guides.md#how-to-migrate-from-techdocs-alpha-to-beta) - -**v1** ✅ - -TechDocs packages: - -- '@backstage/plugin-techdocs' -- '@backstage/plugin-techdocs-backend' -- '@backstage/plugin-techdocs-node' -- '@techdocs/cli' - -TechDocs promoted to v1.0! To understand how this change affects the package, please check out our [versioning policy](https://backstage.io/docs/overview/versioning-policy). - -**v1.2** 🚧 - -With the Backstage 1.2 release, we plan to introduce the [TechDocs Addon Framework](https://github.com/backstage/backstage/issues/9636) for augmenting the TechDocs experience at read-time. - -In addition to the framework itself, we'll be open sourcing a `` addon, helping you to create a feedback loop that drives up documentation quality and fosters a documentation culture at your organization. - -### **Next** - -- What can we do in TechDocs to drive up documentation quality? - -### **Someday/Maybe** - -- Contribute to and deploy from a marketplace of TechDocs Addons -- Addon: MDX (allows you to use JSX in your Markdown content) -- Can we go static site generator agnostic? -- Better integration with - [Scaffolder V2](https://github.com/backstage/backstage/issues/2771) (e.g. easy to choose and apply documentation template with Software Templates) -- Possible to configure several aspects about TechDocs (e.g. URL, homepage, - theme) +[Reach out to us](#get-involved) if you want to request more providers. ## Tech stack -| Stack | Location | -| ----------------------------------------------- | --------------------------------------------------------------- | -| Frontend Plugin | [`@backstage/plugin-techdocs`][techdocs/frontend] | -| Frontend Plugin Library | [`@backstage/plugin-techdocs-react`][techdocs/frontend-library] | -| Backend Plugin | [`@backstage/plugin-techdocs-backend`][techdocs/backend] | -| CLI (for local development and generating docs) | [`@techdocs/cli`][techdocs/cli] | -| Docker Container (for generating docs) | [`techdocs-container`][techdocs/container] | +| Stack | Location | +| ----------------------------------------------- | ------------------------------------------------------------- | +| Frontend Plugin | [@backstage/plugin-techdocs][techdocs/frontend] | +| Frontend Plugin Library | [@backstage/plugin-techdocs-react][techdocs/frontend-library] | +| Backend Plugin | [@backstage/plugin-techdocs-backend][techdocs/backend] | +| CLI (for local development and generating docs) | [@techdocs/cli][techdocs/cli] | +| Docker Container (for generating docs) | [techdocs-container][techdocs/container] | [techdocs/frontend]: https://github.com/backstage/backstage/blob/master/plugins/techdocs [techdocs/frontend-library]: https://github.com/backstage/backstage/blob/master/plugins/techdocs-react @@ -112,7 +97,34 @@ In addition to the framework itself, we'll be open sourcing a `` [techdocs/container]: https://github.com/backstage/techdocs-container [techdocs/cli]: https://github.com/backstage/techdocs-cli -## Contact us +## Get involved -Reach out to us in the `#docs-like-code` channel of our +Reach out to us in the **#docs-like-code** channel of our [Discord chatroom](https://github.com/backstage/backstage#community). + +## Done + +**Alpha release** + +[Milestone](https://github.com/backstage/backstage/milestone/16) + +- Alpha of TechDocs that you can use end to end - and contribute to. + +**Beta release** + +[Milestone](https://github.com/backstage/backstage/milestone/29) + +- TechDocs' recommended setup supports most environments (CI systems, cloud + storage solutions, source control systems). +- [Instructions for upgrading from Alpha to Beta](how-to-guides.md#how-to-migrate-from-techdocs-alpha-to-beta) + +**v1.0** + +TechDocs promoted to v1.0! To understand how this change affects the package, check out our [versioning policy](https://backstage.io/docs/overview/versioning-policy). + +TechDocs packages: + +- @backstage/plugin-techdocs +- @backstage/plugin-techdocs-backend +- @backstage/plugin-techdocs-node +- @techdocs/cli diff --git a/docs/overview/roadmap.md b/docs/overview/roadmap.md index 106bf56f79..727000728f 100644 --- a/docs/overview/roadmap.md +++ b/docs/overview/roadmap.md @@ -12,12 +12,12 @@ and the broader Backstage community. The Backstage roadmap lays out both [“what's next”](#whats-next) and ["future work"](#future-work). With "next" we mean features planned for release within -the ongoing quarter from January through March 2022. With "future" we mean +the ongoing quarter from April through June 2022. With "future" we mean features on the radar, but not yet scheduled. -| [What's next](#whats-next) | [Future work](#future-work) | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -| [Ease of onboarding](#ease-of-onboarding)
[Search 1.0](#search-1.0)
[TechDocs Addon framework](#techdocs-addon-framework)
[Backend Services (initial)](#backend-services-initial)
[Backstage Security Audit](#backstage-security-audit)
[SIGs for contributors](#sigs-for-contributors) | Security Plan (and Strategy)
Composable Homepage 1.0
GraphQL
Telemetry
Improved UX design | +| [What's next](#whats-next) | [Future work](#future-work) | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| [Ease of onboarding](#ease-of-onboarding)
[Backstage Search 1.0](#search-1.0)
[TechDocs Addon Framework](#techdocs-addon-framework)
[Backend Services (initial)](#backend-services-initial)
[Backstage Security Audit](#backstage-security-audit)
[SIGs for contributors](#sigs-for-contributors) | Security Plan (and Strategy)
Composable Homepage 1.0
GraphQL
Telemetry
Improved UX design | The long-term roadmap (12 - 36 months) is not detailed in the public roadmap. Third-party contributions are also not currently included in the roadmap. Let us @@ -46,18 +46,17 @@ More iterations will be required in the following quarters, but this will be a good improvement in the onboarding experience, especially for the benefit of new adopters. -### Search 1.0 +### Backstage Search 1.0 -Fix the few remaining issues to get Backstage Search platform up to 1.0 -([here](https://github.com/backstage/backstage/milestone/27) and -[here](https://github.com/backstage/backstage/milestone/28)). +Fix the few remaining issues to get Backstage Search platform up to 1.0. For more information, see the [Backstage Search documentation and roadmap page](https://backstage.io/docs/features/search/search-overview). -### TechDocs Addon framework +### TechDocs Addon Framework -Addons are TechDocs features that are added on top of the base docs-like-code -experience. An example would be a feature that showed comments on the page. We -plan to add an Addon framework and open source a selection of the Addons that we -use internally at Spotify. Further Addons can then be added by the Community. +Addons are TechDocs features that are added on top of the base docs-like-code experience. An example would be a feature that showed comments on the page. We plan to add an Addon framework and open source a selection of the Addons that we use internally at Spotify. We encourage the Backstage community to add further Addons. + +For more information about the TechDocs Addon Framework, see the documentation page [here](https://backstage.io/docs/features/techdocs/addons) + +For general information about TechDocs including roadmap, see [here](https://backstage.io/docs/features/techdocs/techdocs-overview). ### Backend Services (initial)