feat: TechDocs - Add vale linter to check words quality in md files. (b…

…ackstage#2631)

* fix(docs): typos which were reflacted from vale linter's command

* feat: Implement Vale linter (backstage#2031)
Initialize .vale.ini file
Add 'lint:docs' script to package.json, to lint all md files except the ones which are located in node_modules
Generate 'vocab.txt' by using command 'yarn run lint:docs' | grep -o ''[a-z A-Z]*'' | grep -o '[a-z A-Z]*' | sort | uniq > .github/styles/vocab.txt
Add steps to github workflow 'master' to check docs quality

* chore: Separate workflow for quality checking

* chore: Added 'shx' dev dependency to support grep command in cross platform

* feat: Add script to operate same quality check process on different platform

* ignore: remove lint:docs from lint-stages which was added for experiment purpose

* fix: check-all-files on push event & check-changed-files on pull_request event

* chore(CI): triggle workflow only when there is any updates in .md file(s) on pull request

* fix: use spawnSync to solve 'The command line is too long.' error

* fix: github workflow syntax

* fix: prettier error

* chore: add vale command directly to lint-staged

* chore: use shebang for easy access

* fix: windows script issue & remove shebang

* chore: Add shebang flag

* chore: better error message related to vale

* chore: mention vale linter in documentation

* fix: spelling errors & add keywords to vocab.txt

.github/styles/vocab.txt

@@ -0,0 +1,203 @@
+abc
+Apdex
+api
+Api
+apis
+args
+asciidoc
+async
+Avro
+backrub
+Balachandran
+Bigtable
+Blackbox
+bool
+boolean
+Chai
+changeset
+changesets
+Changesets
+changset
+chanwit
+Chanwit
+cisphobia
+cissexist
+classname
+cli
+cncf
+codeblocks
+Codecov
+codehilite
+Codehilite
+codeowners
+config
+Config
+configs
+const
+cookiecutter
+css
+dariddler
+deadnaming
+destructured
+dev
+devs
+discoverability
+Discoverability
+dls
+docgen
+Dockerfile
+Dockerize
+dockerode
+Docusaurus
+eg
+Ek
+env
+Env
+eslint
+facto
+failover
+Figma
+Firekube
+Fredrik
+github
+Github
+Gitlab
+graphql
+graphviz
+Hackathons
+haproxy
+heroku
+Hostname
+http
+https
+img
+incentivised
+inlinehilite
+interop
+javascript
+Javascript
+jq
+js
+json
+jsx
+Kaewkasi
+Knex
+kubectl
+kubernetes
+learnings
+lerna
+Lerna
+magiclink
+mailto
+Malus
+md
+microsite
+middleware
+minikube
+Minikube
+misgendering
+mkdocs
+Mkdocs
+monorepo
+Monorepo
+monorepos
+msw
+namespace
+Namespaces
+neuro
+newrelic
+nginx
+Niklas
+nohoist
+nonces
+npm
+nvm
+oauth
+Oauth
+Okta
+Oldsberg
+onboarding
+Onboarding
+pagerduty
+Patrik
+Phoen
+plantuml
+Pomaceous
+postgres
+pre
+prebaked
+preconfigured
+Preprarer
+Prerequisities
+productional
+Protobuf
+proxying
+Proxying
+pygments
+pymdownx
+Raghunandan
+rankdir
+readme
+Readme
+Redash
+repo
+Repo
+repos
+rerender
+rollbar
+Rollbar
+Rollup
+Rosaceae
+rst
+rsync
+ruleset
+sam
+scaffolded
+scaffolder
+Scaffolder
+semlas
+Serverless
+Sinon
+smartsymobls
+sparklines
+Spotifiers
+spotify
+Spotify
+squidfunk
+src
+subkey
+superfences
+Superfences
+talkdesk
+Talkdesk
+tasklist
+techdocs
+templated
+templater
+Templater
+templaters
+Templaters
+Thauer
+theres
+toc
+tolerations
+Tolerations
+toolsets
+touchpoints
+ui
+upvote
+url
+utils
+validators
+Voi
+Wealthsimple
+Weaveworks
+xyz
+yaml
+Zalando
+Zhou
+Billett
+cloudbuild
+Grafana
+Iain
+Snyk

.github/workflows/docs-quality-checker.yml

@@ -0,0 +1,18 @@
+name: Check Markdown files quality
+
+on:
+  pull_request:
+    branches: [master]
+    paths:
+      - '**.md'
+
+jobs:
+  check-all-files:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: documentation quality check
+        uses: errata-ai/vale-action@v1.3.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.vale.ini

@@ -0,0 +1,4 @@
+StylesPath = .github/styles
+
+[*.md]
+BasedOnStyles = Vale

CONTRIBUTING.md

@@ -76,6 +76,8 @@ If you're contributing to the backend or CLI tooling, be mindful of cross-platfo
 
 Also be sure to skim through our [ADRs](https://github.com/spotify/backstage/tree/master/docs/architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](https://github.com/spotify/backstage/blob/master/docs/architecture-decisions/adr006-avoid-react-fc.md) is one to look out for.
 
+If there are any updates in `markdown` file please make sure to run `yarn run lint:docs`. Though it is checked on `lint-staged`. It is required to install [vale](https://docs.errata.ai/vale/install) separately and make sure it is accessed by global command.
+
 # Creating Changesets
 
 We use [changesets](https://github.com/atlassian/changesets) to help us prepare releases. It helps us make sure that every package affected by a change gets a proper version number and an entry in its `CHANGELOG.md`. To make the process of generating releases easy. it helps when contributors include changesets with their pull requests.

DEPLOYMENT.md

@@ -4,7 +4,7 @@
 
 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 into it as well as loging into Heroku's [container registry](https://devcenter.heroku.com/articles/container-registry-and-runtime).
+First, make sure you have the [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).
 
 ```bash
 $ heroku login

docs/features/software-templates/extending/create-your-own-preparer.md

@@ -88,7 +88,7 @@ Some good examples exist here:
 - https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/stages/prepare/file.ts
 - https://github.com/spotify/backstage/blob/master/plugins/scaffolder-backend/src/scaffolder/stages/prepare/github.ts
 
-### Registerinng your own Preparer
+### Registering your own Preparer
 
 You can register the preparer that you have created with the `PreparerBuilder`
 by using the `PreparerKey` from the Catalog, for example like this:

docs/features/techdocs/FAQ.md

@@ -35,4 +35,4 @@ well as a selection of Python Markdown extensions that TechDocs supports.
 Not right now. We are currently using MkDocs to generate the documentation from
 source, so the files have to be in Markdown format. However, in the future we
 want to support other static site generators which will make it possible to use
-otherfile formats.
+other file formats.

docs/plugins/testing.md

@@ -166,7 +166,7 @@ because it fulfills all the principles above:
 ✓ **Fulfills Input/Output Principle**: Verifies the output changes when the
 input changes
 
-✓ **Fufills Blackbox Principle**: Does not verify _how_ the `<Loading />`
+✓ **Fulfills Blackbox Principle**: Does not verify _how_ the `<Loading />`
 component is mounted, just that it is mounted in response to the input.
 
 ✓ **Fulfills Scalability Principle**: If we decide to refactor the entire way

docs/reference/utility-apis/AlertApi.md

@@ -73,7 +73,7 @@ Referenced by: [alert\$](#alert).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 

docs/reference/utility-apis/AppThemeApi.md

@@ -135,7 +135,7 @@ Referenced by: [activeThemeId\$](#activethemeid).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 

docs/reference/utility-apis/ErrorApi.md

@@ -93,7 +93,7 @@ Referenced by: [error\$](#error).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 

docs/reference/utility-apis/OAuthRequestApi.md

@@ -11,7 +11,8 @@ The following Utility API implements this type:
 ### createAuthRequester()
 
 A utility for showing login popups or similar things, and merging together
-multiple requests for different scopes into one request that inclues all scopes.
+multiple requests for different scopes into one request that includes all
+scopes.
 
 The passed in options provide information about the login provider, and how to
 handle auth requests.
@@ -30,7 +31,7 @@ createAuthRequester<AuthResponse>(
 
 ### authRequest\$()
 
-Observers panding auth requests. The returned observable will emit all current
+Observers pending auth requests. The returned observable will emit all current
 active auth request, at most one for each created auth requester.
 
 Each request has its own info about the login provider, forwarded from the auth
@@ -156,7 +157,7 @@ Referenced by: [authRequest\$](#authrequest).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 

docs/reference/utility-apis/SessionApi.md

@@ -81,7 +81,7 @@ Referenced by: [sessionState\$](#sessionstate).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 

docs/reference/utility-apis/SessionStateApi.md

@@ -62,7 +62,7 @@ Referenced by: [sessionState\$](#sessionstate).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 

docs/reference/utility-apis/StorageApi.md

@@ -35,7 +35,7 @@ remove(key: string): Promise<void>
 
 ### set()
 
-Save persistant data, and emit messages to anyone that is using observe\$ for
+Save persistent data, and emit messages to anyone that is using observe\$ for
 this key
 
 <pre>
@@ -85,7 +85,7 @@ Referenced by: [observe\$](#observe), [StorageApi](#storageapi).
 
 ### Observer
 
-This file contains non-react related core types used throught Backstage.
+This file contains non-react related core types used through Backstage.
 
 Observer interface for consuming an Observer, see TC39.
 
@@ -129,7 +129,7 @@ export interface StorageApi {
   remove(key: string): Promise&lt;void&gt;;
 
   /**
-   * Save persistant data, and emit messages to anyone that is using observe$ for this key
+   * Save persistent data, and emit messages to anyone that is using observe$ for this key
    *
    * @param {String} key Unique key associated with the data.
    */

package.json

@@ -16,6 +16,7 @@
     "test": "lerna run test --since origin/master -- --coverage",
     "test:all": "lerna run test -- --coverage",
     "lint": "lerna run lint --since origin/master --",
+    "lint:docs": "node ./scripts/check-docs-quality",
     "lint:all": "lerna run lint --",
     "lint:type-deps": "node scripts/check-type-dependencies.js",
     "docgen": "lerna run docgen",
@@ -46,7 +47,8 @@
     "lerna": "^3.20.2",
     "lint-staged": "^10.1.0",
     "prettier": "^2.0.5",
-    "recursive-readdir": "^2.2.2"
+    "recursive-readdir": "^2.2.2",
+    "shx": "^0.3.2"
   },
   "husky": {
     "hooks": {
@@ -61,6 +63,9 @@
     ],
     "*.{json,md}": [
       "prettier --write"
+    ],
+    "*.md": [
+      "vale"
     ]
   },
   "jest": {