Try out Vale linter for our Markdown files

[HonkingGoose]

Describe the proposed change(s).

Find out if Vale will work for us.

Introduction

Vale is a command line tool to lint our Markdown files for style errors.
The project can be found on GitHub: https://github.com/errata-ai/vale

Todos:

• Try out Vale with default settings
• Find way to run Vale in Gitpod container (run brew install vale)
• Find way to run Vale in .devcontainer on GitHub
• Find out how enforce the Plain language guidelines with Vale
• Find out how to customize the allowed/rejected vocabulary lists
• Setup GitHub Action for Vale linter on main repository
• Setup GitHub Action for Vale linter on docs publishing repository
• Pin version of Vale everywhere we use it:
  • Gitpod
  • GitHub Codespaces
  • GitHub Action file(s)

[HonkingGoose]

@viceice or @rarkins Is the brew package manager pre-installed in your codespaces enviroment? On Gitpod brew comes with their default image, but I don't know how you've set up your Codespaces. 😉

[viceice]

no, it's not on our code spaces image.

[viceice]

we don't need brew, as the required binary can be easily downloaded from releases page

https://docs.errata.ai/vale/install#using-vale-with-a-continuous-integration-ci-service

[HonkingGoose]

@viceice Does GitHub Codespaces come with the official gh CLI program? The Vale docs say:

If you want to use Vale with a CI service, we recommend that you use the official GitHub CLI tool to download the version of your choice from the releases page

$ gh release download --repo 'errata-ai/vale' -p 'vale_2.11.2_Linux_64-bit.tar.gz'
$ tar -xf 'vale_2.11.2_Linux_64-bit.tar.gz'
$ ./vale -v

This will ensure that your CI builds are consistent and allow you to update versions on an opt-in basis.

[viceice]

nope, we can easily add an installer to our buildbpack, so updates are supported out of the box 🤗

[JamieMagee]

It can also be run as a Docker container. That would simplify the install process.

[rarkins]

It can also be run as a Docker container. That would simplify the install process.

But that means a dev would need Docker locally to run all tests?

[rarkins]

This is another reason I'd love to have seamless codespaces or gitpod for this project so that drive by contributors can easily test their changes

[HonkingGoose]

Adding installer to our buildpack

we don't need brew, as the required binary can be easily downloaded from releases page

nope, we can easily add an installer to our buildpack, so updates are supported out of the box 🤗

I found these files in the repository:

renovate/.devcontainer/devcontainer.json

Lines 1 to 19 in a8930b7

	{
	"name": "Renovate",
	"dockerFile": "Dockerfile",
	"settings": {
	"terminal.integrated.shell.linux": "/bin/bash"
	},
	"extensions": [
	"dbaeumer.vscode-eslint",
	"esbenp.prettier-vscode",
	"orta.vscode-jest"
	],
	"runArgs": [
	"--cap-add=SYS_PTRACE",
	"--security-opt",
	"seccomp=unconfined",
	"--privileged"
	],
	"postCreateCommand": "yarn install"
	}

renovate/.devcontainer/Dockerfile

Lines 1 to 6 in a8930b7

	FROM containerbase/node:14.19.1@sha256:a22aa48fbdcc09fde9f6c2f2e2caa5db713b89266015f8678eaf5c12575628c8
	USER root
	# renovate: datasource=npm
	RUN install-tool yarn 1.22.18

So I think you want to edit the Dockerfile so it fetches the Vale program from their GitHub releases?

Running Vale as a Docker container

It can also be run as a Docker container. That would simplify the install process.

Gitpod supports a custom Dockerfile ¹, which we could use to load the official Vale Docker image. But I got stuck trying to create a custom Dockerfile for our basic Gitpod config, see: #12210, so I'm not really keen on messing with that again. 😄🙈

Version control for Vale

We should pin the version of Vale in all our files that will end up using Vale:

• Gitpod
• Codespaces
• GitHub Action

I'll add a todo to my list in the original post, so we don't forget this.

Footnotes

1. https://www.gitpod.io/docs/config-docker ↩

[HonkingGoose]

I think the Vale linter is very cool. Unfortunately I can't get it working in a way that's suitable for us. I still hope to find a good linter that can help us with following our style guide, and to find typos, and so on.

For now, I'm closing this issue as not planned.