From ab120c01f771f58990c149036ab67e9ea053fe33 Mon Sep 17 00:00:00 2001
From: joao-paulo-parity <joao-paulo@parity.io>
Date: Thu, 2 Sep 2021 00:29:05 -0300
Subject: [PATCH] update readme

---
 README.md | 70 ++++++++++++++++++++-----------------------------------
 1 file changed, 25 insertions(+), 45 deletions(-)

diff --git a/README.md b/README.md
index e5128e7..c47936a 100644
--- a/README.md
+++ b/README.md
@@ -9,8 +9,8 @@ The bot runs commands in response to pull request comments
 
 `/bench [action] [...args]`
 
-For the response to work, [environment variables](#configuration) and
-[Github settings](#github-settings) have to properly configured upfront.
+[Environment variables](#configuration) and [Github settings](#github-settings)
+have to properly configured upfront for this interaction to work.
 
 ## Configuration
 
@@ -26,10 +26,9 @@ WEBHOOK_SECRET=<Webhook secret from Github App Settings>
 WEBHOOK_PROXY_URL=<optional; webhook proxy for development>
 ```
 
-For development it's recommended to use [smee](https://smee.io) for
-`WEBHOOK_PROXY_URL`; that way you can test your changes locally without having
-to SSH into the dedicated machine - it avoids disrupting the production
-service.
+During development it's recommended to use [smee](https://smee.io) for
+`WEBHOOK_PROXY_URL` because it enables testing your bot's functionality
+locally, without having to SSH into the dedicated machine.
 
 ## Running
 
@@ -39,54 +38,35 @@ service.
 
 ### Dedicated machine
 
-Note: Before disrupting the production deployment, it's first recommended to
-check if some benchmark is running with `pgrep -au benchbot`. With SSH:
+_Note: Before disrupting the production deployment, it's first recommended to
+check if some benchmark is running through_ `pgrep -a cargo` _._
 
-`ssh user@remote 'sudo pgrep -au benchbot'`
-
-And check if the command above shows any `cargo` or `rust` command being ran
-currently (for the Rust benchmarks).
-
-#### Introduction
-
-The [run](./run) script is used to manage the application.
+The [run script](./run) is used to manage the application. Use `run help` for
+documentation about its options.
 
 `run bootstrap` will take care of creating and installing everything from
-scratch. After installation, a systemd service will be created for you to
-manage with `run {start,restart,stop,status}` which acts as a wrapper for
-`systemctl`.
-
-#### Updating branches
-
-The `update` subcommand will fetch and restart the bot with the selected branch. e.g.
-
-`ssh user@remote '/home/benchbot/bench-bot/run update master'`
-
-For pull requests, the format is `pull/${ID}/head:${BRANCH}` as per the
-[Github specification](https://docs.github.com/en/github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally#modifying-an-inactive-pull-request-locally). e.g.
-
-`ssh user@remote '/home/benchbot/bench-bot/run update pull/1/head:branch'`
-
-#### Setting up
-
-By default the bot will be bootstrapped to `/home/benchbot/bench-bot` and
-executed by the `benchbot` user. From your machine, execute the `run` script
-remotely with SSH:
-
-`ssh user@remote '/home/benchbot/bench-bot/run [command]'`
-
-e.g.
+scratch. For it to fully work, you'll also need to set up [environment
+variables](#configuration) which optionally through a `.env` file in the bot's
+directory.
 
-`ssh user@remote '/home/benchbot/bench-bot/run restart'`
+The bot's execution is controlled through:
 
+- `run {start,stop,restart}`: execute the relevant action for the bot.
+- `run update [ref]`: restart the bot with the branch or PR
+  - For branch: `ssh user@remote '/home/benchbot/bench-bot/run update master'`
+  - For PR: `ssh user@remote '/home/benchbot/bench-bot/run update pull/number/head:branch'` 
+    e.g. `pull/1/head:master`
 
-#### Additional information
+Additionally, a monitoring service will be created and it can be managed as:
 
-The full explanation for all commands is available with `run help`.
+- `run monitor {install,uninstall}`: install or uninstall the monitoring
+  service
+- `run monitor {start,restart,stop,status,...}`: acts as a wrapper for
+  `systemctl`
 
-After it's running, the logs will be to the systemd journal:
+The logs will be output to the systemd journal:
 
-`sudo journalctl -u benchbot.service`
+`sudo journalctl -u benchbot-monitor.service`
 
 As well as to `./log.txt`.