diff --git a/docs/auth/auth-backend-classes.md b/docs/auth/auth-backend-classes.md index 9dc677b439..442553d4b8 100644 --- a/docs/auth/auth-backend-classes.md +++ b/docs/auth/auth-backend-classes.md @@ -20,7 +20,7 @@ Each of these methods is hosted at an endpoint `/auth/[provider]/method`, where ``` For more information on how these methods are used and for which purpose, refer -to the documentation [here](oauth.md). +to the [OAuth documentation](oauth.md). For details on the parameters, input and output conditions for each method, refer to the type documentation under @@ -38,7 +38,7 @@ Currently OAuth is assumed to be the de facto authentication mechanism for Backstage based applications. Backstage comes with a "batteries-included" set of supported commonly used OAuth -providers: Okta, Github, Google, Gitlab, and a generic OAuth2 provider. +providers: Okta, GitHub, Google, GitLab, and a generic OAuth2 provider. All of these use the authorization flow of OAuth2 to implement authentication. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 4ca2f431a7..855c8b0634 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -23,8 +23,8 @@ Requests towards this repo. Backstage provides the `@backstage/create-app` package to scaffold standalone instances of Backstage. You will need to have -[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed -(currently v12), [yarn](https://classic.yarnpkg.com/en/docs/install) and +[Node.js](https://nodejs.org/en/download/) Active LTS Release installed +(currently v12), [Yarn](https://classic.yarnpkg.com/en/docs/install) and [Python](https://www.python.org/downloads/) (although you likely have it already). You will also need to have [Docker](https://docs.docker.com/engine/install/) installed to use some features @@ -38,8 +38,8 @@ 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](https://backstage.io/docs/getting-started/create-an-app). +look something like this. You can read more about this process in +[Create an app](https://backstage.io/docs/getting-started/create-an-app). ### Contributing to Backstage diff --git a/docs/getting-started/running-backstage-locally.md b/docs/getting-started/running-backstage-locally.md index 6e6c8b2733..1a9097afd3 100644 --- a/docs/getting-started/running-backstage-locally.md +++ b/docs/getting-started/running-backstage-locally.md @@ -8,7 +8,7 @@ description: Documentation on How to run Backstage Locally - Node.js -First make sure you are using NodeJS with an Active LTS Release, currently v12. +First make sure you are using Node.js with an Active LTS Release, currently v12. This is made easy with a version manager such as [nvm](https://github.com/nvm-sh/nvm) which allows for version switching. @@ -23,10 +23,10 @@ node --version > v12.18.3 ``` -- yarn +- Yarn Please refer to the -[installation instructions for yarn](https://classic.yarnpkg.com/en/docs/install/). +[installation instructions for Yarn](https://classic.yarnpkg.com/en/docs/install/). - Docker diff --git a/docs/overview/architecture-overview.md b/docs/overview/architecture-overview.md index 8edf3e9e4c..504d6ea2c9 100644 --- a/docs/overview/architecture-overview.md +++ b/docs/overview/architecture-overview.md @@ -48,7 +48,7 @@ management. [[live demo](https://backstage-demo.roadie.io/)] ![UI with different components highlighted](../assets/architecture-overview/core-vs-plugin-components-highlighted.png) Each plugin typically makes itself available in the UI on a dedicated URL. For -example, the lighthouse plugin is registered with the UI on `/lighthouse`. +example, the Lighthouse plugin is registered with the UI on `/lighthouse`. [[live demo](https://backstage-demo.roadie.io/lighthouse)] ![The lighthouse plugin UI](../assets/architecture-overview/lighthouse-plugin.png) @@ -76,7 +76,7 @@ Plugins can be enabled, and passed configuration in `apis.ts`. For example, [here](https://github.com/spotify/backstage/blob/master/packages/app/src/apis.ts) is that file in the Backstage sample app. -This is how the lighthouse plugin would be enabled in a typical Backstage +This is how the Lighthouse plugin would be enabled in a typical Backstage application: ```tsx @@ -108,7 +108,7 @@ Architecturally, plugins can take three forms: #### Standalone plugins Standalone plugins run entirely in the browser. -[The tech radar plugin](https://backstage-demo.roadie.io/tech-radar), for +[The Tech Radar plugin](https://backstage-demo.roadie.io/tech-radar), for example, simply renders hard-coded information. It doesn't make any API requests to other services. @@ -124,9 +124,9 @@ simple. Service backed plugins make API requests to a service which is within the purview of the organisation running Backstage. -The lighthouse plugin, for example, makes requests to the +The Lighthouse plugin, for example, makes requests to the [lighthouse-audit-service](https://github.com/spotify/lighthouse-audit-service). -The lighthouse-audit-service is a microservice which runs a copy of Google's +The `lighthouse-audit-service` is a microservice which runs a copy of Google's [Lighthouse library](https://github.com/GoogleChrome/lighthouse/) and stores the results in a PostgreSQL database. @@ -144,11 +144,11 @@ Third-party backed plugins are similar to service backed plugins. The main difference is that the service which backs the plugin is hosted outside of the ecosystem of the company hosting Backstage. -The Circle CI plugin is an example of a third-party backed plugin. Circle CI is -a SaaS service which can be used without any knowledge of Backstage. It has an -API which a Backstage plugin consumes to display content. +The CircleCI plugin is an example of a third-party backed plugin. CircleCI is a +SaaS service which can be used without any knowledge of Backstage. It has an API +which a Backstage plugin consumes to display content. -Requests which go to Circle CI from the users browser are passed through a proxy +Requests which go to CircleCI from the users browser are passed through a proxy service that Backstage provides. Without this, the requests would be blocked by Cross Origin Resource Sharing policies which prevent a browser page served at [https://example.com](https://example.com) from serving resources hosted at @@ -180,7 +180,7 @@ separate docker images. 1. The frontend container 2. The backend container -3. The lighthouse audit service container +3. The Lighthouse audit service container ![Boxes around the architecture to indicate how it is containerised](../assets/architecture-overview/containerised.png) @@ -204,7 +204,7 @@ yarn run docker-build This will create a container called `example-backend`. The lighthouse-audit-service container is already publicly available in Docker -Hub and can be downloaded and ran with +Hub and can be downloaded and run with ```bash docker run spotify/lighthouse-audit-service:latest diff --git a/docs/plugins/structure-of-a-plugin.md b/docs/plugins/structure-of-a-plugin.md index ee0a27cde2..0f11896f7a 100644 --- a/docs/plugins/structure-of-a-plugin.md +++ b/docs/plugins/structure-of-a-plugin.md @@ -73,7 +73,7 @@ export const plugin = createPlugin({ ``` This is where the plugin is created and where it hooks into the app by declaring -what component should be shown on what url. See reference docs for +what component should be shown on what URL. See reference docs for [createPlugin](../reference/createPlugin.md) or [router](../reference/createPlugin-router.md). @@ -101,11 +101,11 @@ Backstage CLI. ## Talking to the outside world -If your plugin needs to communicate with services outside the backstage +If your plugin needs to communicate with services outside the Backstage environment you will probably face challenges like CORS policies and/or backend-side authorization. To smooth this process out you can use proxy - -either the one you already have (like nginx/haproxy/etc) or the proxy-backend -plugin that we provide for the backstage backend. +either the one you already have (like Nginx, HAProxy, etc.) or the proxy-backend +plugin that we provide for the Backstage backend. [Read more](https://github.com/spotify/backstage/blob/master/plugins/proxy-backend/README.md) [Back to Getting Started](../README.md) diff --git a/docs/support/project-structure.md b/docs/support/project-structure.md index 987d6a8ff3..fd8e76d58a 100644 --- a/docs/support/project-structure.md +++ b/docs/support/project-structure.md @@ -71,38 +71,38 @@ Let's look at them individually. ### `packages/` -These are all the packages that is we use within the project. -[Plugins](#plugins) are separated out into their own folder, see further down. +These are all the packages that we use within the project. [Plugins](#plugins) +are separated out into their own folder, see further down. - [`app/`](https://github.com/spotify/backstage/tree/master/packages/app) - This is our take on how an App could look like, bringing together a set of packages and plugins into a working Backstage App. This is not a published package, and - the main goals is to provide a demo of what an App could look like, and also - enabling local development. + the main goals are to provide a demo of what an App could look like and to + enable local development. - [`backend/`](https://github.com/spotify/backstage/tree/master/packages/backend) - - Every standalone backstage project will have both an `app` _and_ a `backend` + Every standalone Backstage project will have both an `app` _and_ a `backend` package. The `backend` uses plugins to construct a working backend that the frontend (`app`) can use. - [`backend-common/`](https://github.com/spotify/backstage/tree/master/packages/backend-common) - There are no "core" packages in the backend. Instead we have `backend-common` - which contains helper middleware´s and other utils. + which contains helper middleware and other utils. - [`catalog-model/`](https://github.com/spotify/backstage/tree/master/packages/catalog-model) - - You can considers this to be a library for working with the catalog of sorts. + You can consider this to be a library for working with the catalog of sorts. It contains the definition of an [Entity](https://backstage.io/docs/features/software-catalog/references#docsNav), - as well as validation an other logic related to it. This package can be used + as well as validation and other logic related to it. This package can be used in both the frontend and the backend. - [`cli/`](https://github.com/spotify/backstage/tree/master/packages/cli) - One of the biggest packages in our project, the `cli` is used to build, serve, diff, create-plugins and more. In the early days of this project, we started - out with calling tools directly - such as `eslint` - through package.json. But - as it was tricky to have a good development experience around that when we + out with calling tools directly - such as `eslint` - through `package.json`. + But as it was tricky to have a good development experience around that when we change named tooling, we opted for wrapping those in our own cli. That way - everything looks the same in package.json. Much like + everything looks the same in `package.json`. Much like [react-scripts](https://github.com/facebook/create-react-app/tree/master/packages/react-scripts). - [`cli-common/`](https://github.com/spotify/backstage/tree/master/packages/cli-common) - @@ -119,20 +119,21 @@ These are all the packages that is we use within the project. * [`config-loader/`](https://github.com/spotify/backstage/tree/master/packages/config-loader) - This package is used to read config objects. It does not know how to merge, - this only reads files and passes them on to the config. As this part os only + but only reads files and passes them on to the config. As this part is only used by the backend, we chose to separate `config` and `config-loader` into two different packages. - [`core/`](https://github.com/spotify/backstage/tree/master/packages/core) - This package contains our visual React components, some of which you can find - [here](https://backstage.io/storybook/?path=/story/plugins-examples--plugin-with-data). + in + [plugin examples](https://backstage.io/storybook/?path=/story/plugins-examples--plugin-with-data). Apart from that it re-exports everything from [`core-api`] so that users only need to rely on one package. * [`core-api/`](https://github.com/spotify/backstage/tree/master/packages/core-api) - - This package contains apis and definitions of such. It is it's own package + This package contains APIs and definitions of such. It is it's own package because we needed to split our `test-utils` package. It's an implementation - detail that we try to hide from our users, and no-one should have to depend on + detail that we try to hide from our users, and no one should have to depend on it directly. * [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils) - @@ -140,7 +141,7 @@ These are all the packages that is we use within the project. `core-api`. * [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core) - - This package contains more general purpose testing facilities for testing an + This package contains more general purpose testing facilities for testing a Backstage App. * [`create-app/`](https://github.com/spotify/backstage/tree/master/packages/create-app) - @@ -181,7 +182,7 @@ These are all the packages that is we use within the project. ### `plugins/` -Most of the functionality of an Backstage App comes from plugins. Even core +Most of the functionality of a Backstage App comes from plugins. Even core features can be plugins, take the [catalog](https://github.com/spotify/backstage/tree/master/plugins/catalog) as an example. @@ -199,7 +200,7 @@ through the ## Packages outside of the monorepo -For convenience we include packages in our project that is not part of our +For convenience we include packages in our project that are not part of our monorepo setup. - [`microsite/`](https://github.com/spotify/backstage/blob/master/microsite) - @@ -220,17 +221,17 @@ future. that this folder use the public registry. - [`.vale.ini`](https://github.com/spotify/backstage/tree/master/.vale.ini) - - [Spell checker](https://github.com/errata-ai/vale) for markdown files + [Spell checker](https://github.com/errata-ai/vale) for Markdown files. - [`.yarnrc`](https://github.com/spotify/backstage/tree/master/.yarnrc) - - Enforces "our" version of yarn. + Enforces "our" version of Yarn. - [`app-config.yaml`](https://github.com/spotify/backstage/tree/master/app-config.yaml) - - Configuration for the app, both frontend and backend + Configuration for the app, both frontend and backend. - [`catalog-info.yaml`](https://github.com/spotify/backstage/tree/master/catalog-info.yaml) - Description of Backstage in the Backstage Entity format. - [`lerna.json`](https://github.com/spotify/backstage/tree/master/lerna.json) - - [lerna](https://github.com/lerna/lerna) monorepo config. We are using + [Lerna](https://github.com/lerna/lerna) monorepo config. We are using `yarn workspaces`, so this will only be used for executing scripts. diff --git a/docs/tutorials/journey.md b/docs/tutorials/journey.md index 908d7fc61b..059782de33 100644 --- a/docs/tutorials/journey.md +++ b/docs/tutorials/journey.md @@ -179,7 +179,7 @@ const onSave = async () => { ``` Now it's much simpler for users to change the theme tune, as they no longer need -to go look up a track ID and edit a yaml file. Instead, they can now stay inside +to go look up a track ID and edit a YAML file. Instead, they can now stay inside Backstage and search for the track and request the change from there. In addition, the requested change can be reviewed by the regular process of each organization. diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md index 8f6b35617b..7fc7e739f2 100644 --- a/docs/tutorials/quickstart-app-auth.md +++ b/docs/tutorials/quickstart-app-auth.md @@ -11,7 +11,7 @@ title: Monorepo App Setup With Authentication > own environment. It starts with a skeleton install and verifying of the > monorepo's functionality. Next, GitHub authentication is added and tested. > -> This document assumes you have NodeJS 12 active along with Yarn and Python. +> This document assumes you have Node.js 12 active along with Yarn and Python. > Please note, that at the time of this writing, the current version is > 0.1.1-alpha.21. This guide can still be used with future versions, just, > verify as you go. If you run into issues, you can compare your setup with mine diff --git a/docs/tutorials/quickstart-app-plugin.md b/docs/tutorials/quickstart-app-plugin.md index 9f571b0c9a..daf76aa1cd 100644 --- a/docs/tutorials/quickstart-app-plugin.md +++ b/docs/tutorials/quickstart-app-plugin.md @@ -20,7 +20,7 @@ title: Adding Custom Plugin to Existing Monorepo App > functionality, extend the Sidebar to make our life easy. Finally, we add > custom code to display GitHub repository information. > -> This document assumes you have NodeJS 12 active along with Yarn and Python. +> This document assumes you have Node.js 12 active along with Yarn and Python. > Please note, that at the time of this writing, the current version is > 0.1.1-alpha.21. This guide can still be used with future versions, just, > verify as you go. If you run into issues, you can compare your setup with mine @@ -161,7 +161,7 @@ export default ExampleFetchComponent; # The Graph Model -GitHub has a graphql API available for interacting. Let's start by adding our +GitHub has a GraphQL API available for interacting. Let's start by adding our basic repository query 1. Add the query const statement outside ExampleFetchComponent