paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 40 Packages Projects Releases Wiki Activity

Merge pull request #11593 from backstage/roadmap-updates

Browse Source 
roadmap-updates
This commit is contained in:
Gary Niemen
2022-05-26 17:48:41 +02:00
committed by GitHub
parent ca98fe0b29 75d8a17466
commit 7d96a85399
3 changed files with 164 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/search/README.md
+80 -65
View File
@@ -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.
docs/features/techdocs/README.md
+72 -60
View File
@@ -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 `<ReportIssue />` 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 `<ReportIssue />`
[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
docs/overview/roadmap.md
+12 -13
View File
@@ -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) <br/> [Search 1.0](#search-1.0) <br/> [TechDocs Addon framework](#techdocs-addon-framework) <br/> [Backend Services (initial)](#backend-services-initial) <br/> [Backstage Security Audit](#backstage-security-audit) <br/> [SIGs for contributors](#sigs-for-contributors) | Security Plan (and Strategy) <br/> Composable Homepage 1.0 <br/> GraphQL <br/> Telemetry <br/> Improved UX design |
| [What's next](#whats-next) | [Future work](#future-work) |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| [Ease of onboarding](#ease-of-onboarding) <br/> [Backstage Search 1.0](#search-1.0) <br/> [TechDocs Addon Framework](#techdocs-addon-framework) <br/> [Backend Services (initial)](#backend-services-initial) <br/> [Backstage Security Audit](#backstage-security-audit) <br/> [SIGs for contributors](#sigs-for-contributors) | Security Plan (and Strategy) <br/> Composable Homepage 1.0 <br/> GraphQL <br/> Telemetry <br/> 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)