diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f054de05ce..3513545420 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ 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. -Therefore we want to create strong community of contributors -- all working together to create the kind of delightful experience that our developers deserve. +Therefore we want to a create strong community of contributors -- all working together to create the kind of delightful experience that our developers deserve. Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. ❤️ @@ -100,7 +100,7 @@ Signed-off-by: Jane Smith - In case you forgot to add it to the last N commits in your branch, use `git rebase --signoff HEAD~N` and replace N with the number of new commits you created in your branch. - If you have a very deep branch with a lot of commits, run `git rebase -i --signoff $(git merge-base -a master HEAD)`, double check to make sense of the commits (keep all lines as `pick`) and save and close the editor. This should bulk sign all the commits in your PR. Do be careful though. If you have a complex flow with a lot of branching and re-merging of work branches and stuff, merge-base may not be the right solution for you. -Note: If you have already pushed you branch to a remote, you might have to force push: `git push -f` after the rebase. +Note: If you have already pushed your branch to a remote, you might have to force push: `git push -f` after the rebase. ### Using GitHub Desktop? diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 3bcef61021..e841f7020a 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -24,7 +24,7 @@ To become a maintainer you need to demonstrate the following: - Monitor Discord (delayed response is perfectly acceptable). - Triage GitHub issues and perform pull request reviews for other maintainers and the community. - Triage build issues - file issues for known flaky builds or bugs, and either fix or find someone to fix any master build breakages. -- During GitHub issue triage, apply all applicable ([labels](https://github.com/backstage/backstage/labels)) to each new issue. Labels are extremely useful for future issue follow up. Which labels to apply is somewhat subjective so just use your best judgment. A few of the most important labels that are not self explanatory are: +- During GitHub issue triage, apply all applicable ([labels](https://github.com/backstage/backstage/labels)) to each new issue. Labels are extremely useful for future issue to follow-up. Which labels to apply is somewhat subjective so just use your best judgment. A few of the most important labels that are not self-explanatory are: - good first issue: Mark any issue that can reasonably be accomplished by a new contributor with this label. - help wanted: Unless it is immediately obvious that someone is going to work on an issue (and if so assign it), mark it help wanted. - Make sure that ongoing PRs are moving forward at the right pace or closing them. @@ -71,9 +71,9 @@ The following is a non-exhaustive list of types of change, for which a reviewer - Additions and removals of entire packages - Releases (e.g. pull requests titled `Version Packages`) -A maintainer may suggest an addition to the reviewers team by opening a pull request that modifies [`OWNERS.md`](./OWNERS.md) accordingly. Prospective reviewers are not expected to do this themselves, but should rather ask a maintainer to sponsor their addition. All of the maintainers and sponsors are called to vote on the addition (see the section below about voting). If the vote passes, the pull request can be approved and merged, and the corresponding addition to the GitHub team can be made. +A maintainer may suggest an addition to the reviewers' team by opening a pull request that modifies [`OWNERS.md`](./OWNERS.md) accordingly. Prospective reviewers are not expected to do this themselves, but should rather ask a maintainer to sponsor their addition. All of the maintainers and sponsors are called to vote on the addition (see the section below about voting). If the vote passes, the pull request can be approved and merged, and the corresponding addition to the GitHub team can be made. -A reviewer can elect to remove themselves from the reviewers group by opening, or asking a maintainer to open, a pull request that modifies [`OWNERS.md`](./OWNERS.md) accordingly. A maintainer will approve and merge the pull request, and the corresponding removal from the GitHub team can be made. +A reviewer can elect to remove themselves from the reviewers' group by opening, or asking a maintainer to open, a pull request that modifies [`OWNERS.md`](./OWNERS.md) accordingly. A maintainer will approve and merge the pull request, and the corresponding removal from the GitHub team can be made. A maintainer can call on the other maintainers and sponsors for a vote to remove a reviewer (see the section below about conflict resolution and voting). If the vote passes, a maintainer creates a pull request that modifies [`OWNERS.md`](./OWNERS.md) accordingly. After approval by another maintainer, the pull request can be merged, and the corresponding removal from the GitHub team can be made. diff --git a/STYLE.md b/STYLE.md index d968d387fc..1c40ed241e 100644 --- a/STYLE.md +++ b/STYLE.md @@ -131,7 +131,7 @@ We use [API Extractor](https://api-extractor.com/pages/overview/demo_docs/) to g The doc comments are of the good old `/** ... */` format, with tags of the format `@` used to mark various things. The [TSDoc website](https://tsdoc.org/) has a good index of all available tags. -There are a few things to pay attention to make the documentation show up in a nice way on the website... +There are a few things to pay attention to to make the documentation show up in a nice way on the website... ## Declare exported functions using the `function` keyword @@ -163,7 +163,7 @@ If the parameters of a function are destructed in the parameter list, they will ![image](https://user-images.githubusercontent.com/4984472/133117011-3e6cb6da-40dd-450e-8d33-51bdcf412e08.png) -Instead prefer to use a single parameter variable and then move the destructuring into the function body instead, which will look much nicer: +Instead prefer to use a single parameter variable and then move the destructuring into the function body, which will look much nicer: ![image](https://user-images.githubusercontent.com/4984472/133120542-d648de43-5495-43a8-b532-f5e6f6ab736e.png) diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md index 55285e7f4e..2f989b9cf3 100644 --- a/docs/getting-started/configuration.md +++ b/docs/getting-started/configuration.md @@ -28,7 +28,7 @@ At the end of this tutorial, you can expect: These instructions can be skipped if you already have a PostgreSQL server installed and created a schema and user. The example below is for Linux, but -luckily there's detailed instructions on how to +luckily there are detailed instructions on how to [install PostgreSQL](https://www.postgresql.org/download/) to help you get started. @@ -113,7 +113,7 @@ new component, or register an existing one it will be saved in the database. Later in this tutorial you'll add a service, and you can test if it's persistent as advertised. -If you want to read more about the database configuration, here's some helpful +If you want to read more about the database configuration, here are some helpful links: - [Configuring Plugin Databases](../tutorials/configuring-plugin-databases.md#privileges) @@ -122,7 +122,7 @@ links: ### Setting up authentication -There's multiple authentication providers available for you to use with +There are multiple authentication providers available for you to use with Backstage, feel free to follow [the instructions for adding authentication](../auth/). @@ -191,7 +191,7 @@ components: { That should be it. You can stop your Backstage App. When you start it again and go to your Backstage portal in your browser, you should have your login prompt! -To learn more about Authentication in Backstage, there's the following docs you +To learn more about Authentication in Backstage, here are the following docs you could read: - [Adding Authentication](../auth/) @@ -208,7 +208,7 @@ and Groups can also be loaded from an organization. While using GitHub Apps might be the best way to set up integrations, for this tutorial you'll use a Personal Access Token. -Create your Personal Access Token by opening the +Create your Personal Access Token by opening [the GitHub token creation page](https://github.com/settings/tokens/new). Use a name to identify this token and put it in the notes field. Choose a number of days for expiration. If you have a hard time picking a number, we suggest to go diff --git a/docs/overview/adopting.md b/docs/overview/adopting.md index 152be21a2c..0765d4a452 100644 --- a/docs/overview/adopting.md +++ b/docs/overview/adopting.md @@ -25,7 +25,7 @@ This team will have **four** primary objectives: 2. Drive adoption of customers (developers at your company). -3. Work with senior tech leadership and architects to ensure your organizations +3. Work with senior tech leadership and architects to ensure your organization's best practices for software development are encoded into a set of [Software Templates](../features/software-templates/index.md). @@ -62,7 +62,7 @@ products they maintain. ### Tactics -Example of tactics we have used to evangelize Backstage internally: +Examples of tactics we have used to evangelize Backstage internally: - Arrange "Lunch & Learns" and seminars. Frequently offer teams interested in Backstage development to come to a seminar where you show, for example, how to @@ -77,13 +77,13 @@ Example of tactics we have used to evangelize Backstage internally: - Show & tell meetings. In order to build an internal community around Backstage we have quarterly meetings where anyone working on Backstage is invited to - present their work. This is a not only a great way to get early feedback, but + present their work. This is not only a great way to get early feedback, but also helps coordination between teams that are building overlapping experiences. - Provide metrics. Add instrumentation to your Backstage deployment and make - metrics available to contributing teams. At Spotify we have even gone so far - as sending out weekly digest email showing how usage metrics have changed for + metrics available to contributing teams. At Spotify, we have even gone so far + as to send out weekly digest emails showing how usage metrics have changed for individual plugins. - Pro-actively identify new plugins. Reach out to teams that own internal UIs or @@ -109,12 +109,12 @@ successful impact on your software development process: - **Deploys to production** Cousin to the metric above: How many times does an engineer push changes into production. -- **MTTR** With clear ownership of all the pieces in your micro services +- **MTTR** With clear ownership of all the pieces in your microservices ecosystem and all tools integrated into one place, Backstage makes it quicker for teams to find the root cause of failures, and fix them. - **Context switching** Reducing context switching can help engineers stay in - the "zone". We measure the number of different tools an engineer have to + the "zone". We measure the number of different tools an engineer has to interact with in order to get a certain job done (e.g. push a change, follow it into production and validate it did not break anything). diff --git a/docs/overview/roadmap.md b/docs/overview/roadmap.md index 1c620348bb..8ecd7c4a38 100644 --- a/docs/overview/roadmap.md +++ b/docs/overview/roadmap.md @@ -21,7 +21,7 @@ mean features in the radar, but not yet scheduled. The long-term roadmap (12 - 36 months) is not detailed in the public roadmap. Third-party contributions are also not currently included in the roadmap. Let us -know about any ongoing developments and we’re happy to include it here as well. +know about any ongoing developments and we’re happy to include them here as well. ## What’s next