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

Documentation editorial review (#3055)

Browse Source 
* Fix case and link

* Align product/vendor case

* Reword for readability

* YAML Case

* Align product names

* Align product and acronym case

* Remove here link and product naming

* Align Node.js naming

* Align product names

* Fix wording
This commit is contained in:
Adam Harvey
2020-10-23 02:01:07 -04:00
committed by GitHub
parent 628f782948
commit a06164da24
9 changed files with 51 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/auth/auth-backend-classes.md
+2 -2
View File
@@ -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.
docs/getting-started/index.md
+4 -4
View File
@@ -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
docs/getting-started/running-backstage-locally.md
+3 -3
View File
@@ -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
docs/overview/architecture-overview.md
+11 -11
View File
@@ -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
docs/plugins/structure-of-a-plugin.md
+4 -4
View File
@@ -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)
docs/support/project-structure.md
+23 -22
View File
@@ -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.
docs/tutorials/journey.md
+1 -1
View File
@@ -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.
docs/tutorials/quickstart-app-auth.md
+1 -1
View File
@@ -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
docs/tutorials/quickstart-app-plugin.md
+2 -2
View File
@@ -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