From e7686833fd22db87d1a3f5ac71b9c3109786d285 Mon Sep 17 00:00:00 2001 From: Navaneeth Suresh Date: Mon, 28 Sep 2020 16:48:40 +0530 Subject: [PATCH] docs: fix typos in the documentation (#2633) --- docs/FAQ.md | 4 ++-- docs/api/utility-apis.md | 4 ++-- .../adr002-default-catalog-file-format.md | 4 ++-- .../adr003-avoid-default-exports.md | 2 +- .../adr004-module-export-structure.md | 2 +- docs/architecture-decisions/adr006-avoid-react-fc.md | 2 +- .../adr007-use-msw-to-mock-service-requests.md | 2 +- docs/auth/index.md | 2 +- docs/auth/oauth.md | 4 ++-- docs/features/software-catalog/extending-the-model.md | 4 ++-- docs/features/software-catalog/index.md | 2 +- docs/features/software-catalog/references.md | 4 ++-- docs/features/software-catalog/well-known-annotations.md | 2 +- docs/features/software-templates/adding-templates.md | 6 +++--- .../extending/create-your-own-preparer.md | 4 ++-- .../extending/create-your-own-publisher.md | 8 ++++---- .../extending/create-your-own-templater.md | 2 +- docs/features/software-templates/extending/index.md | 8 ++++---- docs/features/software-templates/installation.md | 2 +- docs/features/techdocs/getting-started.md | 2 +- docs/plugins/index.md | 2 +- docs/plugins/structure-of-a-plugin.md | 2 +- docs/plugins/testing.md | 6 +++--- docs/tutorials/journey.md | 8 ++++---- docs/tutorials/quickstart-app-plugin.md | 4 ++-- 25 files changed, 46 insertions(+), 46 deletions(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index b4c4970ff8..d4d129a0d6 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -86,7 +86,7 @@ well-known tech and a large flora of components. ### What technology does Backstage use? -The code base is a large-scale React application that uses TypeScript. For +The codebase is a large-scale React application that uses TypeScript. For [Phase 2](https://github.com/spotify/backstage#project-roadmap), we plan to use Node.js and GraphQL. @@ -205,7 +205,7 @@ Please report sensitive security issues via Spotify's ### Does Backstage collect any information that is shared with Spotify? No. Backstage does not collect any telemetry from any third party using the -platform. Spotify, and the open source community, does have access to +platform. Spotify, and the open source community, do have access to [GitHub Insights](https://github.com/features/insights), which contains information such as contributors, commits, traffic, and dependencies. Backstage is an open platform, but you are in control of your own data. You control who diff --git a/docs/api/utility-apis.md b/docs/api/utility-apis.md index 599bbbb66c..1ebf2ae88b 100644 --- a/docs/api/utility-apis.md +++ b/docs/api/utility-apis.md @@ -248,8 +248,8 @@ directly tied to React. The indirection provided by Utility APIs also makes it straightforward to test components that depend on APIs, and to provide a standard common development environment for plugins. A proper test wrapper with mocked API implementations -is not yet ready, but it will provided as a part of `@backstage/test-utils`. It -will provide mocked variants of APIs, with additional methods for asserting a +is not yet ready, but it will be provided as a part of `@backstage/test-utils`. +It will provide mocked variants of APIs, with additional methods for asserting a component's interaction with the API. The common development environment for plugins is included in diff --git a/docs/architecture-decisions/adr002-default-catalog-file-format.md b/docs/architecture-decisions/adr002-default-catalog-file-format.md index f4fd3a1158..d831581d5b 100644 --- a/docs/architecture-decisions/adr002-default-catalog-file-format.md +++ b/docs/architecture-decisions/adr002-default-catalog-file-format.md @@ -22,7 +22,7 @@ This ADR describes the default format of these descriptor files. ### Inspiration -Internally at Spotify, a home grown software catalog system is used heavily and +Internally at Spotify, a homegrown software catalog system is used heavily and forms a core part of Backstage and other important pieces of the infrastructure. The user experience, learnings and certain pieces of metadata from that catalog are being carried over to the open source effort. @@ -40,7 +40,7 @@ triggers from the version control system, etc. Each file describes one or more entities in accordance with the [Backstage System Model](https://github.com/spotify/backstage/issues/390). All -of these entities have a common stucture and nomenclature, and they are stored +of these entities have a common structure and nomenclature, and they are stored in the software catalog from which they then can be queried. Entities have distinct names, and they may reference each other by those names. diff --git a/docs/architecture-decisions/adr003-avoid-default-exports.md b/docs/architecture-decisions/adr003-avoid-default-exports.md index 8634a19632..d08bc6a882 100644 --- a/docs/architecture-decisions/adr003-avoid-default-exports.md +++ b/docs/architecture-decisions/adr003-avoid-default-exports.md @@ -44,7 +44,7 @@ A summary: name each. Using named exports helps prevent needing to rename symbols, which has myriad -benefts. A few are: +benefits. A few are: - IDE tools like "Find All References" and "Go To Definition" function - Manual codebase searching ("grep", etc) is easier with a unique symbol diff --git a/docs/architecture-decisions/adr004-module-export-structure.md b/docs/architecture-decisions/adr004-module-export-structure.md index 85f06c6894..14c94c4ed1 100644 --- a/docs/architecture-decisions/adr004-module-export-structure.md +++ b/docs/architecture-decisions/adr004-module-export-structure.md @@ -22,7 +22,7 @@ or We currently do not use any pattern for how to structure exports. There is a mix of package-level re-exports deep into the directory tree, shallow re-exports for each directory, exports using `*` and explicit lists of each symbol, etc. The -mix and lack of predictability makes it difficult to reason about the boundaries +mix and lack of predictability make it difficult to reason about the boundaries of a module, and for example knowing whether it is safe to export a symbol in a given file. diff --git a/docs/architecture-decisions/adr006-avoid-react-fc.md b/docs/architecture-decisions/adr006-avoid-react-fc.md index bea36712d7..4aafa307cf 100644 --- a/docs/architecture-decisions/adr006-avoid-react-fc.md +++ b/docs/architecture-decisions/adr006-avoid-react-fc.md @@ -13,7 +13,7 @@ with next to no benefits in combination with a few downsides. The main reasons were: - **children props** were implicitly added -- **Generic Type** were not supported on children +- **Generic Type** was not supported on children Read more about the removal in [this PR](https://github.com/facebook/create-react-app/pull/8177). diff --git a/docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md b/docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md index 6b18f67d40..045588f505 100644 --- a/docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md +++ b/docs/architecture-decisions/adr007-use-msw-to-mock-service-requests.md @@ -11,7 +11,7 @@ tests, unit tests to e2e tests always have their own implementation of mocking these requests. There's been traction in the outer community towards using this library to mock network requests by using an express style declaration for routes. react-testing-library suggests using this library instead of mocking -fetch directly wether this be in a browser or in node. +fetch directly whether this be in a browser or in node. https://github.com/mswjs/msw diff --git a/docs/auth/index.md b/docs/auth/index.md index aed3a580b0..d7fb5d8c59 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -6,7 +6,7 @@ description: Documentation on User Authentication and Authorization in Backstage ## Summary -The purpose of the Auth APIs in Backstage are to identify the user, and to +The purpose of the Auth APIs in Backstage is to identify the user, and to provide a way for plugins to request access to 3rd party services on behalf of the user (OAuth). This documentation focuses on the implementation of that solution and how to extend it. For documentation on how to consume the Auth APIs diff --git a/docs/auth/oauth.md b/docs/auth/oauth.md index e90b7b665a..178b99b153 100644 --- a/docs/auth/oauth.md +++ b/docs/auth/oauth.md @@ -52,7 +52,7 @@ in a new popup window that is opened by the app. By using a popup-based flow it is possible to request authentication at any point in the app, without requiring a redirect. Because of this there is no need to ask for all scopes upfront, or interrupt the app with a redirect and forcing plugin authors to take care in -restoring state after a redirect has been make. All in all it makes it much +restoring state after a redirect has been made. All in all it makes it much easier to make authenticated requests inside a plugin. ## OAuth Flow @@ -67,7 +67,7 @@ Component and APIs can request Access or ID Tokens from any available Auth provider. If there already exists a cached fresh token that covers (at least) the requested scopes, it will be returned immediately. If the OAuth provider implements token refreshes, this check will also trigger a token refresh attempt -if no session is a available. +if no session is available. If new scopes are requested, or the user is not yet logged in with that provider, a dialog is shown informing the user that they need to log in with the diff --git a/docs/features/software-catalog/extending-the-model.md b/docs/features/software-catalog/extending-the-model.md index 4e8a357ea7..7e2a4c3867 100644 --- a/docs/features/software-catalog/extending-the-model.md +++ b/docs/features/software-catalog/extending-the-model.md @@ -18,7 +18,7 @@ Backstage natively supports tracking of the following component Since these types are likely not the only kind of software you will want to track in Backstage, it is possible to -It is possible to add your own software types that fits your organization's data +It is possible to add your own software types that fit your organization's data model. Inside Spotify our model has grown significantly over the years, and now includes ML models, Apps, data pipelines and many more. @@ -30,7 +30,7 @@ catalog. ## The Other type It might be tempting to put software that doesn't fit into any of the existing -types into Other. There are a few reasons why we advice against this; firstly, +types into Other. There are a few reasons why we advise against this; firstly, we have found that it is preferred to match the conceptual model that your engineers have when describing your software. Secondly, Backstage helps your engineers manage their software by integrating the infrastructure tooling diff --git a/docs/features/software-catalog/index.md b/docs/features/software-catalog/index.md index 49a490d78b..8be6a00579 100644 --- a/docs/features/software-catalog/index.md +++ b/docs/features/software-catalog/index.md @@ -84,7 +84,7 @@ registered in the catalog. ### Static catalog configuration In addition to manually registering components, it is also possible to register -components though [static configuration](../../conf/index.md). For example, the +components through [static configuration](../../conf/index.md). For example, the above example can be added using the following configuration: ```yaml diff --git a/docs/features/software-catalog/references.md b/docs/features/software-catalog/references.md index 5093ecc49e..e438ddc977 100644 --- a/docs/features/software-catalog/references.md +++ b/docs/features/software-catalog/references.md @@ -67,7 +67,7 @@ be left out in its own yaml file because that's the default value there too), and name `pet-managers`. The entries in `implementsApis` are also references. In this case, none of them -need to specify a kind since we know from the context that that's the only kind +needs to specify a kind since we know from the context that that's the only kind that's supported here. The second entry specifies a namespace but the other ones don't, and in this context, the default is to refer to the same namespace as the originating entity (`external-systems` here). So the three references @@ -79,7 +79,7 @@ there to exist three API kind entities in the catalog matching those references. This is a more verbose version of a reference, where each part of the kind-namespace-name triplet is expressed as a field in a structure. This format -can be used where necessary, such as if either of the three elements contain +can be used where necessary, such as if either of the three elements contains colons or forward slashes. Avoid using it where possible, since it is harder to read and write for humans. diff --git a/docs/features/software-catalog/well-known-annotations.md b/docs/features/software-catalog/well-known-annotations.md index e5b66bb3b2..e0fc10ff1e 100644 --- a/docs/features/software-catalog/well-known-annotations.md +++ b/docs/features/software-catalog/well-known-annotations.md @@ -57,7 +57,7 @@ spec: This annotation allows to fetch an API definition from another location, instead of wrapping the API definition inside the definition field. This allows to -easitly consume existing API definition. The definition is fetched during +easily consume existing API definition. The definition is fetched during ingestion by a processor and included in the entity. It is updated on every refresh. The annotation contains a location reference string that contains the location processor type and the target. diff --git a/docs/features/software-templates/adding-templates.md b/docs/features/software-templates/adding-templates.md index 59019e754e..4283af7c72 100644 --- a/docs/features/software-templates/adding-templates.md +++ b/docs/features/software-templates/adding-templates.md @@ -5,7 +5,7 @@ description: Documentation on Adding your own Templates --- Templates are stored in the **Service Catalog** under a kind `Template`. The -minimum that the a template skeleton needs is a `template.yaml` but it would be +minimum that the template skeleton needs is a `template.yaml` but it would be good to also have some files in there that can be templated in. A simple `template.yaml` definition might look something like this: @@ -30,7 +30,7 @@ spec: templater: cookiecutter # what does this template create type: website - # if the template is not in the current directory where this definition is kept then specfiy + # if the template is not in the current directory where this definition is kept then specify path: './template' # the schema for the form which is displayed in the frontend. # should follow JSON schema for forms: https://jsonforms.io/ @@ -107,7 +107,7 @@ This should then have added the catalog, and also should now be listed under the create page at http://localhost:3000/create. The `type` field which is chosen in the request to add the `template.yaml` to -the Service Catalog here, will be come the `PreparerKey` which will be used to +the Service Catalog here, will become the `PreparerKey` which will be used to select the `Preparer` when creating a job. ### Adding form values in the Scaffolder Wizard diff --git a/docs/features/software-templates/extending/create-your-own-preparer.md b/docs/features/software-templates/extending/create-your-own-preparer.md index 14c75b0ffb..e354c0941e 100644 --- a/docs/features/software-templates/extending/create-your-own-preparer.md +++ b/docs/features/software-templates/extending/create-your-own-preparer.md @@ -17,7 +17,7 @@ location protocols: These two are added to the `PreparersBuilder` and then passed into the `createRouter` function of the `@spotify/plugin-scaffolder-backend` -An full example backend can be found +A full example backend can be found [here](https://github.com/spotify/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts), but it looks something like the following @@ -98,4 +98,4 @@ const preparers = new Preparers(); preparers.register('gcs', new GoogleCloudStoragePreparer()); ``` -And then pass this in to the `createRouter` function. +And then pass this into the `createRouter` function. diff --git a/docs/features/software-templates/extending/create-your-own-publisher.md b/docs/features/software-templates/extending/create-your-own-publisher.md index 25d7bcf676..ecb097f9d9 100644 --- a/docs/features/software-templates/extending/create-your-own-publisher.md +++ b/docs/features/software-templates/extending/create-your-own-publisher.md @@ -8,10 +8,10 @@ Publishers are responsible for pushing and storing the templated skeleton after the values have been templated by the `Templater`. See [Create your own templater](./create-your-own-templater.md) for more info. -They receive a directory or location where the templater has sucessfully run and -is now ready to store somewhere. They also are given some other options which -are sent from the frontend, such as the `storePath` which is a string of where -the frontend thinks we should save this templated folder. +They receive a directory or location where the templater has successfully run +and is now ready to store somewhere. They also are given some other options +which are sent from the frontend, such as the `storePath` which is a string of +where the frontend thinks we should save this templated folder. Currently we provide the following `publishers`: diff --git a/docs/features/software-templates/extending/create-your-own-templater.md b/docs/features/software-templates/extending/create-your-own-templater.md index 36c362b9c3..d4a6eef5d2 100644 --- a/docs/features/software-templates/extending/create-your-own-templater.md +++ b/docs/features/software-templates/extending/create-your-own-templater.md @@ -147,4 +147,4 @@ const templaters = new Templaters(); templaters.register('handlebars', new HandlebarsTemplater()); ``` -And then pass this in to the `createRouter` function. +And then pass this into the `createRouter` function. diff --git a/docs/features/software-templates/extending/index.md b/docs/features/software-templates/extending/index.md index 02d27a5725..944bf0e3ca 100644 --- a/docs/features/software-templates/extending/index.md +++ b/docs/features/software-templates/extending/index.md @@ -11,13 +11,13 @@ You're at the right place. This guide is going to take you through how the Scaffolder in Backstage works. We'll dive into some jargon and run through what's going on in the backend to be able to create these templates. There's also more guides that you might find -useful at the bottom of this document. At it's core, theres 3 simple stages. +useful at the bottom of this document. At its core, there are 3 simple stages. 1. Pick a skeleton 2. Template some variables into the skeleton 3. Send the templated skeleton somewhere -These three steps are translated to the folllowing stages under the hood in the +These three steps are translated to the following stages under the hood in the scaffolder that you will need to know: 1. Prepare @@ -38,7 +38,7 @@ the router to pick the correct `Preparer` to run for the `Template` entity. **Templater** - The templater is responsible for actually running the chosen templater on top of the previously returned temporary directory from the -**Preprarer**. We advise making these Docker containers as it can keep all +**Preparer**. We advise making these Docker containers as it can keep all dependencies--for example Cookiecutter--self contained and not a dependency on the host machine. @@ -82,7 +82,7 @@ Once that has been posted, a job will be setup with different stages, and the job processor will complete each stage before moving onto the next stage, whilst collecting logs and mutating the running job. -Here's some futher reading that you might find useful: +Here's some further reading that you might find useful: - [Adding your own Template](../adding-templates.md) - [Creating your own Templater](./create-your-own-templater.md) diff --git a/docs/features/software-templates/installation.md b/docs/features/software-templates/installation.md index 90d25cab81..9bd36ff4dd 100644 --- a/docs/features/software-templates/installation.md +++ b/docs/features/software-templates/installation.md @@ -240,7 +240,7 @@ scaffolder: You can configure who can see the new repositories that the scaffolder creates by specifying `visibility` option. Valid options are `public`, `private` and -`internal`. `internal` options is for GitHub Enterprise clients, which means +`internal`. `internal` option is for GitHub Enterprise clients, which means public within the organization. ### Running the Backend diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 03494564c3..2e5c8d000d 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -13,7 +13,7 @@ If you haven't setup Backstage already, start ## Installing TechDocs TechDocs is provided with the Backstage application by default. If you want to -set up TechDocs manually, keep follow the instructions below. +set up TechDocs manually, keep following the instructions below. ### Adding the package diff --git a/docs/plugins/index.md b/docs/plugins/index.md index 32cbfebc4b..8836c1cd42 100644 --- a/docs/plugins/index.md +++ b/docs/plugins/index.md @@ -21,7 +21,7 @@ To create a plugin, follow the steps outlined [here](create-a-plugin.md). ## Suggesting a plugin If you start developing a plugin that you aim to release as open source, we -suggest that you create a new +suggest that you create a [new Issue](https://github.com/spotify/backstage/issues/new?labels=plugin&template=plugin_template.md&title=%5BPlugin%5D+THE+PLUGIN+NAME). This helps the community know what plugins are in development. diff --git a/docs/plugins/structure-of-a-plugin.md b/docs/plugins/structure-of-a-plugin.md index f061d2f4a8..ee0a27cde2 100644 --- a/docs/plugins/structure-of-a-plugin.md +++ b/docs/plugins/structure-of-a-plugin.md @@ -84,7 +84,7 @@ structure our plugins. There are usually one or multiple page components and next to them you can split up the UI in as many components as you feel like. We have the `ExamplePage` to show an example Backstage page component. The -`ExampleFetchComponent` show cases the common task of making an async request to +`ExampleFetchComponent` showcases the common task of making an async request to a public API and plot the response data in a table using Material-UI components. You may tweak these components, rename them and/or replace them completely. diff --git a/docs/plugins/testing.md b/docs/plugins/testing.md index 696f8b1368..bb5a577c7d 100644 --- a/docs/plugins/testing.md +++ b/docs/plugins/testing.md @@ -32,7 +32,7 @@ working on. ## Naming Test Files -Tests should be name `[filename].test.js`. +Tests should be named `[filename].test.js`. For example, the tests for **`Link.js`** exist in the file **`Link.test.js`**. @@ -54,7 +54,7 @@ TODO. # Writing Unit Tests -The following principles are good guides to determining if you are writing high +The following principles are good guides for determining if you are writing high quality frontend unit tests. ## Bad Unit Test Principle @@ -170,7 +170,7 @@ input changes component is mounted, just that it is mounted in response to the input. ✓ **Fulfills Scalability Principle**: If we decide to refactor the entire way -the loading indicator is displayed the test still works without touching it. +the loading indicator has displayed the test still works without touching it. ✓ **Fulfills Broken Functionality Principle**: this test verifies the functionality (displaying an indicator) is working, rather than how it is diff --git a/docs/tutorials/journey.md b/docs/tutorials/journey.md index 24765e8531..908d7fc61b 100644 --- a/docs/tutorials/journey.md +++ b/docs/tutorials/journey.md @@ -134,7 +134,7 @@ work. # 5. The First User At this point the only things that anyone that wants to use Sam's plugin needs -to do is to add +to do are to add https://raw.githubusercontent.com/sam/backstage-spotify-theme/master/annotation.json#/sam.wise/spotify-track-id to their catalog schema, import and add the `PlayerWidget` on the desired entity template pages, and make sure they're providing Spotify auth. @@ -145,7 +145,7 @@ select a theme tune when creating a new component. Sam jumps on the idea and adds a new creation hook that is exported by the plugin. The hook can be installed either in a single, all, or component templates that match a label. It adds a field as a part of the component creation process with a nice search box -that allow users to search for a track that they want to use as the theme tune. +that allows users to search for a track that they want to use as the theme tune. # 6. Return to the Repo @@ -203,7 +203,7 @@ backend plugin also extends the common GraphQL schema with a mutation that updates the track ID in the database. On the frontend the Pull Request doesn't change much. It defines the save action -the was previously using the `RepoApi` in it's own API. +the was previously using the `RepoApi` in its own API. ```ts type ThemeTuneStorageApi = { @@ -247,7 +247,7 @@ 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 suggest a new well-known metadata +to the Backstage Core repo. The request suggests a new well-known metadata annotation called `spotify.com/track-id`, with the same schema definition as Sam's label, and refers to Sam's own plugin and the `spotify-album-art` plugin as existing usages. The Backstage maintainers merge the Pull Request, after diff --git a/docs/tutorials/quickstart-app-plugin.md b/docs/tutorials/quickstart-app-plugin.md index 87bc1bb38a..020c43a294 100644 --- a/docs/tutorials/quickstart-app-plugin.md +++ b/docs/tutorials/quickstart-app-plugin.md @@ -312,6 +312,6 @@ return ( > Break apart ExampleFetchComponent into smaller logical parts contained in > their own files. Rename your components to something other than ExampleXxx. > -> You might be real proud of a plugin you develop. Follow this next tutorial for -> an in-depth look at publishing and including that for the entire Backstage +> You might be really proud of a plugin you develop. Follow this next tutorial +> for an in-depth look at publishing and including that for the entire Backstage > community. [TODO](#).