From 3a6f4415eb163a82dbd1e968001cec843c9597b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20=C3=85lund?= Date: Tue, 18 Aug 2020 10:52:56 +0200 Subject: [PATCH] [Docs] Detailed roadmap and vision (#1991) * [Docs] Update roadmap and vision * Add shield to roadmap * Update roadmap.md * Link to .io in main README * Fix verify links? --- README.md | 34 ++---- docs/README.md | 1 + docs/overview/roadmap.md | 63 +++++++--- docs/overview/vision.md | 21 ++++ docs/overview/what-is-backstage.md | 6 +- microsite/README copy.md | 182 ----------------------------- microsite/core/Footer.js | 31 +---- microsite/i18n/en.json | 3 + microsite/sidebars.json | 3 +- mkdocs.yml | 1 + 10 files changed, 95 insertions(+), 250 deletions(-) create mode 100644 docs/overview/vision.md delete mode 100644 microsite/README copy.md diff --git a/README.md b/README.md index 9a1622cda7..982997a347 100644 --- a/README.md +++ b/README.md @@ -18,26 +18,16 @@ Backstage unifies all your infrastructure tooling, services, and documentation t Out of the box, Backstage includes: -- [Backstage Service Catalog](https://github.com/spotify/backstage/blob/master/docs/features/software-catalog/index.md) for managing all your software (microservices, libraries, data pipelines, websites, ML models, etc.) -- [Backstage Software Templates](https://github.com/spotify/backstage/blob/master/docs/features/software-templates/index.md) for quickly spinning up new projects and standardizing your tooling with your organization’s best practices -- [Backstage TechDocs](https://github.com/spotify/backstage/tree/master/docs/features/techdocs) for making it easy to create, maintain, find, and use technical documentation, using a "docs like code" approach +- [Backstage Service Catalog]((https://backstage.io/docs/features/software-catalog/software-catalog-overview) for managing all your software (microservices, libraries, data pipelines, websites, ML models, etc.) +- [Backstage Software Templates](https://backstage.io/docs/features/software-templates/software-templates-index) for quickly spinning up new projects and standardizing your tooling with your organization’s best practices +- [Backstage TechDocs](https://backstage.io/docs/features/techdocs/techdocs-overview) for making it easy to create, maintain, find, and use technical documentation, using a "docs like code" approach - Plus, a growing ecosystem of [open source plugins](https://github.com/spotify/backstage/tree/master/plugins) that further expand Backstage’s customizability and functionality For more information go to [backstage.io](https://backstage.io) or join our [Discord chatroom](https://discord.gg/EBHEGzX). ## Project roadmap -We created Backstage about 4 years ago. While our internal version of Backstage has had the benefit of time to mature and evolve, the first iteration of our open source version is still nascent. We are envisioning three phases of the project and we have already begun work on various aspects of these phases: - -- 🐣 **Phase 1:** Extensible frontend platform (Done ✅) - You will be able to easily create a single consistent UI layer for your internal infrastructure and tools. A set of reusable [UX patterns and components](http://backstage.io/storybook) help ensure a consistent experience between tools. - -- 🐢 **Phase 2:** Service Catalog ([alpha released](https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha)) - With a single catalog, Backstage makes it easy for a team to manage ten services — and makes it possible for your company to manage thousands of them. Developers can get a uniform overview of all their software and related resources, regardless of how and where they are running, as well as an easy way to onboard and manage those resources. - -- 🐇 **Phase 3:** Ecosystem (later) - Everyone's infrastructure stack is different. By fostering a vibrant community of contributors we hope to provide an ecosystem of Open Source plugins/integrations that allows you to pick the tools that match your stack. - -Check out our [Milestones](https://github.com/spotify/backstage/milestones) and open [RFCs](https://github.com/spotify/backstage/labels/rfc) how they relate to the three Phases outlined above. - -Our vision for Backstage is for it to become the trusted standard toolbox (read: UX layer) for the open source infrastructure landscape. Think of it like Kubernetes for developer experience. We realize this is an ambitious goal. We can’t do it alone. If this sounds interesting or you'd like to help us shape our product vision, we'd love to talk. You can email me directly: [alund@spotify.com](mailto:alund@spotify.com). +A detailed project roadmap, including already delivered milestones, is available [here](https://backstage.io/docs/overview/roadmap). ## Overview @@ -69,7 +59,7 @@ Using `npx` you can then run the following to create an app in a chosen subdirec npx @backstage/create-app ``` -You will be taken through a wizard to create your app, and the output should look something like this. You can read more about this process [here](docs/getting-started/create-an-app.md) +You will be taken through a wizard to create your app, and the output should look something like this. You can read more about this process [here](https://backstage.io/docs/getting-started/create-an-app) ### Contributing to Backstage @@ -77,22 +67,22 @@ You can read more in our [CONTRIBUTING.md](./CONTRIBUTING.md#get-started) guide, ### Next steps -Take a look at the [Getting Started](docs/getting-started/index.md) guide to learn how to set up Backstage, and how to develop on the platform. +Take a look at the [Getting Started](https://backstage.io/docs/getting-started/index) guide to learn how to set up Backstage, and how to develop on the platform. ## Documentation -- [Main documentation](docs/README.md) -- [Service Catalog](docs/features/software-catalog/index.md) -- [Architecture](docs/overview/architecture-terminology.md) ([Decisions](docs/architecture-decisions/index.md)) -- [Designing for Backstage](docs/dls/design.md) -- [Storybook - UI components](http://backstage.io/storybook) +- [Main documentation](https://backstage.io/docs/overview/what-is-backstage) +- [Service Catalog](https://backstage.io/docs/features/software-catalog/software-catalog-overview) +- [Architecture](https://backstage.io/docs/overview/architecture-terminology) ([Decisions](https://backstage.io/docs/architecture-decisions/adrs-overview)) +- [Designing for Backstage](https://backstage.io/docs/dls/design) +- [Storybook - UI components](https://backstage.io/storybook) ## Community - [Discord chatroom](https://discord.gg/MUpMjP2) - Get support or discuss the project - [Good First Issues](https://github.com/spotify/backstage/contribute) - Start here if you want to contribute - [RFCs](https://github.com/spotify/backstage/labels/rfc) - Help shape the technical direction -- [FAQ](docs/FAQ.md) - Frequently Asked Questions +- [FAQ](https://backstage.io/docs/FAQ) - Frequently Asked Questions - [Code of Conduct](CODE_OF_CONDUCT.md) - This is how we roll - [Adopters](ADOPTERS.md) - Companies already using Backstage - [Blog](https://backstage.io/blog/) - Announcements and updates diff --git a/docs/README.md b/docs/README.md index 9bbc69ca6d..b9e79a9e0a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,6 +11,7 @@ better yet, a pull request. - [Backstage architecture](overview/architecture-overview.md) - [Architecture and terminology](overview/architecture-terminology.md) - [Roadmap](overview/roadmap.md) + - [Vision](overview/vision.md) - Getting started - [Running Backstage locally](getting-started/index.md) - [Installation](getting-started/installation.md) diff --git a/docs/overview/roadmap.md b/docs/overview/roadmap.md index 6acea71509..97020a3a22 100644 --- a/docs/overview/roadmap.md +++ b/docs/overview/roadmap.md @@ -3,37 +3,66 @@ id: roadmap title: Project roadmap --- -We created Backstage about 4 years ago. While our internal version of Backstage -has had the benefit of time to mature and evolve, the first iteration of our -open source version is still nascent. We are envisioning three phases of the -project and we have already begun work on various aspects of these phases: +## Current status + +Backstage is currently in Alpha. This means that you can expect APIs and +features to change until we reach our +[Backstage Beta milestone](https://github.com/spotify/backstage/milestone/19). +Before we have API stability, plugins will need ongoing maintenance. It is also +recommended that teams who adopt Backstage today upgrades their installation as +new [releases](https://github.com/spotify/backstage/releases) are available. + +## Phases + +We have divided the project into three high-level _phases_ and we have already +begun work on various aspects of these phases: - 🐣 **Phase 1:** Extensible frontend platform (Done ✅) - You will be able to easily create a single consistent UI layer for your internal infrastructure and tools. A set of reusable - [UX patterns and components](http://backstage.io/storybook) help ensure a + [UX patterns and components](https://backstage.io/storybook) help ensure a consistent experience between tools. - 🐢 **Phase 2:** Service Catalog ([alpha released](https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha)) - With a single catalog, Backstage makes it easy for a team to manage ten services — and makes it possible for your company to manage thousands of them. - Developers can get a uniform overview of all their software and related - resources, regardless of how and where they are running, as well as an easy - way to onboard and manage those resources. - 🐇 **Phase 3:** Ecosystem (later) - Everyone's infrastructure stack is different. By fostering a vibrant community of contributors we hope to provide an ecosystem of Open Source plugins/integrations that allows you to pick the tools that match your stack. -Check out our [Milestones](https://github.com/spotify/backstage/milestones) and -open [RFCs](https://github.com/spotify/backstage/labels/rfc) how they relate to -the three Phases outlined above. +## Detailed roadmap -Our vision for Backstage is for it to become the trusted standard toolbox (read: -UX layer) for the open source infrastructure landscape. Think of it like -Kubernetes for developer experience. We realize this is an ambitious goal. We -can’t do it alone. If this sounds interesting or you'd like to help us shape our -product vision, we'd love to talk. You can email me directly: -[alund@spotify.com](mailto:alund@spotify.com). +### Ongoing work 🚧 + +- [Plugins for managing micro services end-2-end](https://github.com/spotify/backstage/milestone/14) +- [TechDocs v1](https://github.com/spotify/backstage/milestone/16) +- [Initial GraphQL API](https://github.com/spotify/backstage/milestone/13) +- Backstage Design Language System (DLS) +- Cloud Cost Insights plugin (from Spotify) +- Further improvements to platform documentation + +### Future work 🔮 + +- [Backstage Beta](https://github.com/spotify/backstage/milestone/19) +- [Global search](https://github.com/spotify/backstage/issues/1499) +- [[TechDocs V.2] Stabilization release](https://github.com/spotify/backstage/milestone/17) +- Deploy a product demo at `demo.backstage.io` +- Plugin marketplace + +### Completed milestones ✅ + +- [Improved and move documentation to backstage.io](https://backstage.io/docs/overview/what-is-backstage) +- [Backstage Service Catalog (alpha)](https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha) +- [Backstage Software Templates (alpha)](https://backstage.io/blog/2020/08/05/announcing-backstage-software-templates) +- [Make it possible to add custom auth providers](https://backstage.io/blog/2020/07/01/how-to-enable-authentication-in-backstage-using-passport) +- [TechDocs v0](https://github.com/spotify/backstage/milestone/15) +- CI plugins: CircleCI, Jenkins, GitHub Actions and TravisCI +- [Service API documentation](https://github.com/spotify/backstage/pull/1737) +- Backstage Service Catalog can read from: GitHub, GitLab, + [Bitbucket](https://github.com/spotify/backstage/pull/1938) +- Support auth providers: Google, Okta, GitHub, GitLab, + [auth0](https://github.com/spotify/backstage/pull/1611), + [AWS](https://github.com/spotify/backstage/pull/1990) diff --git a/docs/overview/vision.md b/docs/overview/vision.md new file mode 100644 index 0000000000..2ab7cdc6f4 --- /dev/null +++ b/docs/overview/vision.md @@ -0,0 +1,21 @@ +--- +id: vision +title: Vision +--- + +Our goal is to provide engineers with the best developer experience in the +world. + +A fantastic developer experience leads to happy, creative and productive +engineers. Our belief is that engineers should not have to be experts in various +infrastructure tools to be productive. Infrastructure should be abstracted away +so that you can return to building and scaling, quickly and safely. + +![](https://backstage.io/animations/backstage-logos-hero-8.gif) + +We are working on making Backstage the trusted standard toolbox (read: UX layer) +for the open source infrastructure landscape. Think of it like Kubernetes for +developer experience. We realize this is an ambitious goal. We can’t do it +alone. If this sounds interesting or you'd like to help us shape our product +vision, we'd love to talk. You can email me directly: +[alund@spotify.com](mailto:alund@spotify.com). diff --git a/docs/overview/what-is-backstage.md b/docs/overview/what-is-backstage.md index 163b6c219b..665e172c0b 100644 --- a/docs/overview/what-is-backstage.md +++ b/docs/overview/what-is-backstage.md @@ -28,9 +28,6 @@ Out of the box, Backstage includes: [open source plugins](https://github.com/spotify/backstage/tree/master/plugins) that further expand Backstage’s customizability and functionality -For more information go to [backstage.io](https://backstage.io) or join our -[Discord chatroom](https://discord.gg/EBHEGzX). - ### Benefits - For _engineering managers_, it allows you to maintain standards and best @@ -45,3 +42,6 @@ For more information go to [backstage.io](https://backstage.io) or join our - For _everyone_, it’s a single, consistent experience that ties all your infrastructure tooling, resources, standards, owners, contributors, and administrators together in one place. + +If you have questions or want support, please join our +[Discord chatroom](https://discord.gg/EBHEGzX). diff --git a/microsite/README copy.md b/microsite/README copy.md deleted file mode 100644 index d7187888a3..0000000000 --- a/microsite/README copy.md +++ /dev/null @@ -1,182 +0,0 @@ -This website was created with [Docusaurus](https://docusaurus.io/). - -# What's In This Document - -- [Get Started in 5 Minutes](#get-started-in-5-minutes) -- [Directory Structure](#directory-structure) -- [Editing Content](#editing-content) -- [Adding Content](#adding-content) -- [Full Documentation](#full-documentation) - -## Directory Structure - -Your project file structure should look something like this - -``` -my-docusaurus/ - docs/ - doc-1.md - doc-2.md - doc-3.md - website/ - blog/ - 2016-3-11-oldest-post.md - 2017-10-24-newest-post.md - core/ - node_modules/ - pages/ - static/ - css/ - img/ - package.json - sidebars.json - siteConfig.js -``` - -# Editing Content - -## Editing an existing docs page - -Edit docs by navigating to `docs/` and editing the corresponding document: - -`docs/doc-to-be-edited.md` - -```markdown ---- -id: page-needs-edit -title: This Doc Needs To Be Edited ---- - -Edit me... -``` - -For more information about docs, click [here](https://docusaurus.io/docs/en/navigation) - -## Editing an existing blog post - -Edit blog posts by navigating to `website/blog` and editing the corresponding post: - -`website/blog/post-to-be-edited.md` - -```markdown ---- -id: post-needs-edit -title: This Blog Post Needs To Be Edited ---- - -Edit me... -``` - -For more information about blog posts, click [here](https://docusaurus.io/docs/en/adding-blog) - -# Adding Content - -## Adding a new docs page to an existing sidebar - -1. Create the doc as a new markdown file in `/docs`, example `docs/newly-created-doc.md`: - -```md ---- -id: newly-created-doc -title: This Doc Needs To Be Edited ---- - -My new content here.. -``` - -1. Refer to that doc's ID in an existing sidebar in `website/sidebars.json`: - -```javascript -// Add newly-created-doc to the Getting Started category of docs -{ - "docs": { - "Getting Started": [ - "quick-start", - "newly-created-doc" // new doc here - ], - ... - }, - ... -} -``` - -For more information about adding new docs, click [here](https://docusaurus.io/docs/en/navigation) - -## Adding a new blog post - -1. Make sure there is a header link to your blog in `website/siteConfig.js`: - -`website/siteConfig.js` - -```javascript -headerLinks: [ - ... - { blog: true, label: 'Blog' }, - ... -] -``` - -2. Create the blog post with the format `YYYY-MM-DD-My-Blog-Post-Title.md` in `website/blog`: - -`website/blog/2018-05-21-New-Blog-Post.md` - -```markdown ---- -author: Frank Li -authorURL: https://twitter.com/foobarbaz -authorFBID: 503283835 -title: New Blog Post ---- - -Lorem Ipsum... -``` - -For more information about blog posts, click [here](https://docusaurus.io/docs/en/adding-blog) - -## Adding items to your site's top navigation bar - -1. Add links to docs, custom pages or external links by editing the headerLinks field of `website/siteConfig.js`: - -`website/siteConfig.js` - -```javascript -{ - headerLinks: [ - ... - /* you can add docs */ - { doc: 'my-examples', label: 'Examples' }, - /* you can add custom pages */ - { page: 'help', label: 'Help' }, - /* you can add external links */ - { href: 'https://github.com/facebook/docusaurus', label: 'GitHub' }, - ... - ], - ... -} -``` - -For more information about the navigation bar, click [here](https://docusaurus.io/docs/en/navigation) - -## Adding custom pages - -1. Docusaurus uses React components to build pages. The components are saved as .js files in `website/pages/en`: -1. If you want your page to show up in your navigation header, you will need to update `website/siteConfig.js` to add to the `headerLinks` element: - -`website/siteConfig.js` - -```javascript -{ - headerLinks: [ - ... - { page: 'my-new-custom-page', label: 'My New Custom Page' }, - ... - ], - ... -} -``` - -For more information about custom pages, click [here](https://docusaurus.io/docs/en/custom-pages). - -# Full Documentation - -Full documentation can be found on the [website](https://docusaurus.io/). diff --git a/microsite/core/Footer.js b/microsite/core/Footer.js index c44b8196a6..407bebca84 100644 --- a/microsite/core/Footer.js +++ b/microsite/core/Footer.js @@ -32,22 +32,15 @@ class Footer extends React.Component {
Docs
+ What is Backstage? + Getting started - Create a Plugin - - - Structure of a Plugin - - - API references - - - FAQ + Service Catalog + Create a Plugin + Designing for Backstage
Community
@@ -55,18 +48,6 @@ class Footer extends React.Component { Subscribe to our newsletter - {/* -
Docs
- - Developing a Plugin - - - API Overview - - - Layout Components - - */}
More
diff --git a/microsite/i18n/en.json b/microsite/i18n/en.json index af891426db..40ad25fe53 100644 --- a/microsite/i18n/en.json +++ b/microsite/i18n/en.json @@ -186,6 +186,9 @@ "overview/support": { "title": "Support and community" }, + "overview/vision": { + "title": "Vision" + }, "overview/what-is-backstage": { "title": "What is Backstage?" }, diff --git a/microsite/sidebars.json b/microsite/sidebars.json index d407340471..b07f326086 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -4,7 +4,8 @@ "overview/what-is-backstage", "overview/architecture-overview", "overview/architecture-terminology", - "overview/roadmap" + "overview/roadmap", + "overview/vision" ], "Getting Started": [ "getting-started/index", diff --git a/mkdocs.yml b/mkdocs.yml index 27335903de..085d83b7cc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,6 +7,7 @@ nav: - Backstage architecture: 'overview/architecture-overview.md' - Architecture and terminology: 'overview/architecture-terminology.md' - Roadmap: 'overview/roadmap.md' + - Vision: 'overview/vision.md' - Getting started: - Running Backstage locally: 'getting-started/index.md' - Installation: 'getting-started/installation.md'