diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 3a1db235a0..62ac9da8d8 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -12,7 +12,7 @@ This both applies to objects given to and returned from the software catalog API, as well as to the descriptor files that the software catalog can ingest natively. In the API request/response cycle, a JSON representation is used, while the descriptor files are on YAML format to be more easily maintainable by -humans. However, the structure and semantics is the same in both cases. +humans. However, the structure and semantics are the same in both cases. Although it's possible to name catalog entity descriptor files however you wish, we recommend that you name them `catalog-info.yaml`. @@ -113,7 +113,7 @@ data. Backstage specific entities have an `apiVersion` that is prefixed with `backstage.io/`, to distinguish them from other types of object that share the same type of structure. This may be relevant when co-hosting these -specifications with e.g. kubernetes object manifests, or when an organization +specifications with e.g. Kubernetes object manifests, or when an organization adds their own specific kinds of entity to the catalog. Early versions of the catalog will be using alpha/beta versions, e.g. diff --git a/docs/getting-started/create-an-app.md b/docs/getting-started/create-an-app.md index 670c7fbf98..c35eded6a5 100644 --- a/docs/getting-started/create-an-app.md +++ b/docs/getting-started/create-an-app.md @@ -13,7 +13,7 @@ need to run Backstage in your own environment. ## Create an app To create a Backstage app, you will need to have -[NodeJS](https://nodejs.org/en/download/) Active LTS Release installed +[Node.js](https://nodejs.org/en/download/) Active LTS Release installed (currently v12). Backstage provides a utility for creating new apps. It guides you through the diff --git a/docs/getting-started/deployment-helm.md b/docs/getting-started/deployment-helm.md index e674d28742..c062ed3951 100644 --- a/docs/getting-started/deployment-helm.md +++ b/docs/getting-started/deployment-helm.md @@ -8,10 +8,10 @@ sidebar_label: Kubernetes and Helm # Helm charts An example Backstage app can be deployed in Kubernetes using the -[Backstage Helm charts](https://github.com/spotify/backstage/tree/master/contrib/chart/backstage) +[Backstage Helm charts](https://github.com/spotify/backstage/tree/master/contrib/chart/backstage). -First, choose a DNS name where backstage will be hosted create a yaml file for -your custom configuration. +First, choose a DNS name where Backstage will be hosted, and create a YAML file +for your custom configuration. ```yaml appConfig: @@ -31,7 +31,7 @@ appConfig: Then use it to run: -``` +```bash git clone https://github.com/spotify/backstage.git cd contrib/chart/backstage helm dependency update diff --git a/docs/getting-started/deployment-k8s.md b/docs/getting-started/deployment-k8s.md index 69aa59a600..f123dd2548 100644 --- a/docs/getting-started/deployment-k8s.md +++ b/docs/getting-started/deployment-k8s.md @@ -4,7 +4,7 @@ title: Kubernetes description: Documentation on Kubernetes and K8s Deployment --- -Backstage itself provides tooling up to the point of building docker images. +Backstage itself provides tooling up to the point of building Docker images. Beyond that point we do not have an opinionated way to deploy Backstage within Kubernetes, as each cluster has its own unique set of tooling and patterns. diff --git a/docs/getting-started/deployment-other.md b/docs/getting-started/deployment-other.md index 3e06e17c77..cfd2e903d9 100644 --- a/docs/getting-started/deployment-other.md +++ b/docs/getting-started/deployment-other.md @@ -23,7 +23,7 @@ Then open http://localhost/ on your browser. Deploying to Heroku is relatively easy following these steps. First, make sure you have the -[heroku CLI installed](https://devcenter.heroku.com/articles/heroku-cli) and log +[Heroku CLI installed](https://devcenter.heroku.com/articles/heroku-cli) and log into it as well as login into Heroku's [container registry](https://devcenter.heroku.com/articles/container-registry-and-runtime). @@ -32,7 +32,7 @@ $ heroku login $ heroku container:login ``` -You _might_ also need to set your Heroku app's stack to `container` +You _might_ also need to set your Heroku app's stack to `container`. ```bash $ heroku stack:set container -a diff --git a/docs/overview/architecture-overview.md b/docs/overview/architecture-overview.md index 504d6ea2c9..ee2d3c6097 100644 --- a/docs/overview/architecture-overview.md +++ b/docs/overview/architecture-overview.md @@ -24,7 +24,7 @@ different ways. ## Overview The following diagram shows how Backstage might look when deployed inside a -company which uses the Tech Radar plugin, the Lighthouse plugin, the Circle CI +company which uses the Tech Radar plugin, the Lighthouse plugin, the CircleCI plugin and the service catalog. There are 3 main components in this architecture: @@ -53,9 +53,9 @@ example, the Lighthouse plugin is registered with the UI on `/lighthouse`. ![The lighthouse plugin UI](../assets/architecture-overview/lighthouse-plugin.png) -The Circle CI plugin is available on `/circleci`. +The CircleCI plugin is available on `/circleci`. -![Circle CI Plugin UI](../assets/architecture-overview/circle-ci.png) +![CircleCI Plugin UI](../assets/architecture-overview/circle-ci.png) ## Plugins and plugin backends @@ -154,29 +154,28 @@ Cross Origin Resource Sharing policies which prevent a browser page served at [https://example.com](https://example.com) from serving resources hosted at https://circleci.com. -![CircleCi plugin talking to proxy talking to SaaS Circle CI](../assets/architecture-overview/circle-ci-plugin-architecture.png) +![CircleCI plugin talking to proxy talking to SaaS Circle CI](../assets/architecture-overview/circle-ci-plugin-architecture.png) ## Databases -As we have seen, both the lighthouse-audit-service and catalog-backend require a -database to work with. +As we have seen, both the `lighthouse-audit-service` and `catalog-backend` +require a database to work with. -At the time of writing, the lighthouse-audit-service requires PostgreSQL to work -with. The service catalog backend uses an in-memory Sqlite3 instance. This is a -development oriented setup and there are plans to support other databases in the -future. +At the time of writing, the `lighthouse-audit-service` requires PostgreSQL to +work with. The service catalog backend uses an in-memory Sqlite3 instance. This +is a development-oriented setup and there are plans to support other databases +in the future. -To learn more about the future of databases and Backstage, see the following two +To learn more about the future of databases and Backstage, see the following GitHub issues. -[Knex + Plugins (Multiple vs Single Database) · Issue #1598 · spotify/backstage](https://github.com/spotify/backstage/issues/1598) - -[Update migrations to support postgres by dariddler · Pull Request #1527 · spotify/backstage](https://github.com/spotify/backstage/pull/1527#discussion_r450374145) +- [Knex + Plugins (Multiple vs Single Database) · Issue #1598 · spotify/backstage](https://github.com/spotify/backstage/issues/1598) +- [Update migrations to support postgres by dariddler · Pull Request #1527 · spotify/backstage](https://github.com/spotify/backstage/pull/1527#discussion_r450374145) ## Containerization The example Backstage architecture shown above would Dockerize into three -separate docker images. +separate Docker images. 1. The frontend container 2. The backend container diff --git a/docs/plugins/call-existing-api.md b/docs/plugins/call-existing-api.md index 14ea4c1f5a..3fff90c3f6 100644 --- a/docs/plugins/call-existing-api.md +++ b/docs/plugins/call-existing-api.md @@ -88,7 +88,7 @@ The proxy is powered by the `http-proxy-middleware` package. See [Proxying](proxying.md) for a full description of its configuration options. Internally at Spotify, the proxy option has been the overwhelmingly most popular -choice for plugin makers. Since we have DNS based service discovery in place and +choice for plugin makers. Since we have DNS-based service discovery in place and a microservices framework that made it trivial to expose plain HTTP, it has been a matter of just adding a few lines of Backstage config to get the benefit of being easily and robustly reachable from users' web browsers as well. diff --git a/docs/plugins/testing.md b/docs/plugins/testing.md index c6e1599786..e60b5fa8b7 100644 --- a/docs/plugins/testing.md +++ b/docs/plugins/testing.md @@ -248,15 +248,15 @@ Testing an API involves verifying four things: ### Mocking API Calls -[Mocking in jest](https://facebook.github.io/jest/docs/en/mock-functions.html) +[Mocking in Jest](https://facebook.github.io/jest/docs/en/mock-functions.html) involves wrapping existing functions (like an API call function) with an alternative. For example: -**./Api.js** +**`./MyApi.js`** -``` +```js export { fetchSomethingFromServer: () => { // Live production call to a URI. Must be avoided during testing! @@ -265,9 +265,9 @@ export { }; ``` -**./\_\_mocks\_\_/Api.js** +**`./\_\_mocks\_\_/MyApi.js`** -``` +```js export { fetchSomethingFromServer: () => { // Simulate a production call, but avoid jest and just use a promise @@ -276,16 +276,16 @@ export { } ``` -**./Api.test.js** +**`./MyApi.test.js`** -``` +```js /* eslint-disable import/first */ jest.mock('./MyApi'); // Instruct Jest to swap all future imports of './MyApi.js' to './__mocks__/MyApi.js' import MyApi from './MyApi'; // Will actually return the contents of the file in the __mocks__ folder now -it ('loads data', (done) => { +it('loads data', done => { MyApi.fetchSomethingFromServer().then(result => { expect(result).toBe('some result object simulating server data here'); done(); diff --git a/docs/support/project-structure.md b/docs/support/project-structure.md index fd8e76d58a..9720c4db3e 100644 --- a/docs/support/project-structure.md +++ b/docs/support/project-structure.md @@ -41,10 +41,10 @@ the code. appreciate contributions in here and encourage them being kept up to date. - [`docs/`](https://github.com/spotify/backstage/tree/master/docs) - This is - where we keep all of our documentation markdown files. These ends up on - http://backstage.io/docs. Just keep in mind that changes to - [this](https://github.com/spotify/backstage/blob/master/microsite/sidebars.json) - file also needs to be updated. + where we keep all of our documentation Markdown files. These ends up on + http://backstage.io/docs. Just keep in mind that changes to the + [`sidebars.json`](https://github.com/spotify/backstage/blob/master/microsite/sidebars.json) + file may be needed as sections are added/removed. - [`.editorconfig`](https://github.com/spotify/backstage/tree/master/.editorconfig) - A configuration file used by most common code editors. @@ -111,13 +111,13 @@ are separated out into their own folder, see further down. We also want as few dependencies as possible to reduce download time when running the cli which is another reason this is a separate package. -* [`config/`](https://github.com/spotify/backstage/tree/master/packages/config) - +- [`config/`](https://github.com/spotify/backstage/tree/master/packages/config) - The way we read configuration data. This package can take a bunch of config objects and merge them together. [app-config.yaml](https://github.com/spotify/backstage/blob/master/app-config.yaml) is an example of an config object. -* [`config-loader/`](https://github.com/spotify/backstage/tree/master/packages/config-loader) - +- [`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, 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 @@ -130,21 +130,21 @@ are separated out into their own folder, see further down. 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) - +- [`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 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 it directly. -* [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils) - +- [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils) - This package contains specific testing facilities used when testing `core-api`. -* [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core) - +- [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core) - 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) - +- [`create-app/`](https://github.com/spotify/backstage/tree/master/packages/create-app) - An CLI to specifically scaffold a new Backstage App. It does so by using a [template](https://github.com/spotify/backstage/tree/master/packages/create-app/templates/default-app). @@ -152,32 +152,32 @@ are separated out into their own folder, see further down. Helps you setup a plugin for isolated development so that it can be served separately. -* [`docgen/`](https://github.com/spotify/backstage/tree/master/packages/docgen) - +- [`docgen/`](https://github.com/spotify/backstage/tree/master/packages/docgen) - Uses the [Typescript Compiler API](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API) to read out definitions and generate documentation for it. -* [`e2e-test/`](https://github.com/spotify/backstage/tree/master/packages/e2e-test) - +- [`e2e-test/`](https://github.com/spotify/backstage/tree/master/packages/e2e-test) - Another CLI that can be run to try out what would happen if you built all the packages, publish them, created a new app, and the run it. CI uses this for e2e-tests. -* [`storybook/`](https://github.com/spotify/backstage/tree/master/packages/storybook) - +- [`storybook/`](https://github.com/spotify/backstage/tree/master/packages/storybook) - This folder contains only the storybook config. Stories are within the core package. The Backstage Storybook is found [here](https://backstage.io/storybook) -* [`techdocs-cli/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-cli) - +- [`techdocs-cli/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-cli) - Used for verifying TechDocs locally. -* [`techdocs-container/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-container) - +- [`techdocs-container/`](https://github.com/spotify/backstage/tree/master/packages/techdocs-container) - Used by the `techdocs-cli` -* [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core) +- [`test-utils-core/`](https://github.com/spotify/backstage/tree/master/packages/test-utils-core) -* [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils) +- [`test-utils/`](https://github.com/spotify/backstage/tree/master/packages/test-utils) -* [`theme/`](https://github.com/spotify/backstage/tree/master/packages/theme) - +- [`theme/`](https://github.com/spotify/backstage/tree/master/packages/theme) - Holds the Backstage Theme. ### `plugins/` diff --git a/docs/tutorials/journey.md b/docs/tutorials/journey.md index 059782de33..7627920a75 100644 --- a/docs/tutorials/journey.md +++ b/docs/tutorials/journey.md @@ -239,12 +239,12 @@ hits merge. # 8. Attack of the Clones Sam just released v1.8.4 of the plugin, and at this point it's so popular that a -couple of other plugins has started depending on the `sam.wise/spotify-track-id` -annotation. One such plugin being the `spotify-album-art` plugin that can -display the album art of the theme tune as the background of the entity header. -Sam thinks it's all pretty cool, but doesn't like that the annotation that was -once an internal concern of the plugin is now becoming a standard in the -community. +couple of other plugins have started depending on the +`sam.wise/spotify-track-id` annotation. One such plugin being the +`spotify-album-art` plugin that can display the album art of the theme tune as +the background of the entity header. Sam thinks it's all pretty cool, but +doesn't like that the annotation that was once an internal concern of the plugin +is now becoming a standard in the community. In order to standardize the annotation in Backstage, Sam submits a Pull Request to the Backstage Core repo. The request suggests a new well-known metadata diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md index 7fc7e739f2..1dcca9d7e0 100644 --- a/docs/tutorials/quickstart-app-auth.md +++ b/docs/tutorials/quickstart-app-auth.md @@ -7,7 +7,7 @@ title: Monorepo App Setup With Authentication
-> This document takes you through setting up a backstage app that runs in your +> This document takes you through setting up a Backstage app that runs in your > own environment. It starts with a skeleton install and verifying of the > monorepo's functionality. Next, GitHub authentication is added and tested. >