Skip to content

Offline, privacy-first grammar checker. Fast, open-source, Rust-powered

docs: revise structure and (hopefully) improve explanation

Elijah Potterf6e8ab9e2725
diff --git a/packages/web/src/routes/docs/contributors/review/+page.md b/packages/web/src/routes/docs/contributors/review/+page.md
index 661fd6bbe..6c02b2fb2 100644
--- a/packages/web/src/routes/docs/contributors/review/+page.md
+++ b/packages/web/src/routes/docs/contributors/review/+page.md
@@ -4,19 +4,24 @@ title: Reviewing Pull Requests
There are a lot of individual components and artifacts that make up Harper.
How a patch gets reviewed depends significantly on which component or artifact it affects.
+This page seeks to document the tooling available for downloading and testing patches on a local machine.
-If a patch only affects a grammar rule or otherwise something part of `harper-core` (often it is labeled as such in GitHub), you can build and test the change with **any** of Harper's frontends.
+## Patches to `harper-core`
-## Using GitHub Actions Artifacts
+If a patch only affects a grammar rule, it should only be touching `harper-core`.
+This means you can test the change using any Harper frontend (of which there are many).
+
+### Using GitHub Actions Artifacts
We run builds for a variety of platforms whenever a Pull Request is pushed to.
You can use these to review changes to various aspects of Harper, including `harper-ls`, `harper-cli`, and the Visual Studio Code plugin.
![How to download the Windows Visual Studio Code plugin from the GitHub Actions run.](/images/download_artifact.gif)
-## Using Cargo
+### Testing Using Cargo and `harper-cli`
-If you only have [Cargo](https://doc.rust-lang.org/cargo/) installed, you can compile either `harper-ls` (the language server) or `harper-cli` (our command-line debug tool) directly from the branch in GitHub:
+Most of our build tooling exists for Harper's various integrations.
+If you are testing `harper-core`, you can skip all the fluff and compile the patch using [Cargo](https://doc.rust-lang.org/cargo/) directly.
```bash
cargo install --git https://github.com/automattic/harper --branch <branch-name> <binary-artifact>
@@ -28,9 +33,9 @@ For example, for [PR #445](https://github.com/Automattic/harper/pull/455), we ca
cargo install --git https://github.com/automattic/harper --branch somewhat-something harper-cli
```
-From there you can run the tool on any file with `harper-cli lint`.
+From there, you can run the tool on any file with `harper-cli lint <path>`.
-## Using Docker
+### Testing Via the Docker Image
We build our web documentation in a Docker image.
This documentation includes a [demo](/), so you can also use this image to review changes to linting rules and other aspects of the core algorithm.
@@ -42,3 +47,5 @@ git switch <branch from PR>
IMAGE_HASH=$(docker build . -q)
docker run -p 3000:3000 -it $IMAGE_HASH
```
+
+From there, open up `http://localhost:3000` in your web browser of choice and use the text area to test the change.