Reworded guide, improved line width, ruined diff

docs/development_guide.md

@@ -1,42 +1,84 @@
 Development Guide
 -----------------
 
-This guide is for those that want to help hack on the Slack bridge, and need some instruction on how
-to set it up. This is **not** a guide for setting up an instance for production usage.
+This guide is for those that want to help hack on the Slack bridge, and
+need some instruction on how to set it up. This is **not** a guide for
+setting up an instance for production usage.
 
-For information on how to contribute issues and or pull requests, please read [CONTRIBUTING](../CONTRIBUTING.md).
+For information on how to contribute issues and or pull requests, please
+read [CONTRIBUTING](../CONTRIBUTING.md).
 
 ## Setting up your environment
 
-This section explains how to setup Synapse, Riot and the Slack bridge for local development.
+This section explains how to setup Synapse, Riot and the Slack bridge
+for local development.
 
-### Prereqs 
+### 0. Prerequisites 
 
 Ensure at the minimum you have installed:
 
-- NodeJS ( [nvm](https://github.com/nvm-sh/nvm) is a good tool for this)
-- Docker (optional, but it will make your life easier)
+- NodeJS ([nvm](https://github.com/nvm-sh/nvm) is a good tool for this)
+- Docker
+- `psql` shell utility for accessing the database
+   - On Debian/Ubuntu based systems you can install `postgresql-client`
+   - On a Mac, this is `libpg`
 
-For the sake of making this easier to follow, we will create a directory in the home directory
-called `slack-bridge-env`:
+Docker is used here to reduce the number of requirements on the host system,
+and will allow you to setup your environment faster.
+
+For the sake of making this easier to follow, we will create a directory in
+our home directory called `slack-bridge-env`:
 
 ```bash
 mkdir ~/slack-bridge-env
 cd ~/slack-bridge-env
 ```
 
-### Setting up Synapse
+### 1. Setting up Synapse
+
+Synapse is the reference implementation of a Matrix homeserver. You may use other
+homeserver implementations that support the AS API, but for the sake of simplicity
+this is how to setup Synapse.
+
+To generate your config:
+
+```bash
+docker run -it --rm \
+    -v ~/slack-bridge-env/synapse:/data \
+    -e SYNAPSE_SERVER_NAME=localhost \
+    -e SYNAPSE_REPORT_STATS=no \
+    matrixdotorg/synapse:v1.3.1-py3 generate
+```
+
+Open the generated `homeserver.yaml` file for editing. 
+Find and uncomment the `enable_registration` field, set it to `true`:
+
+```yaml
+enable_registration: true
+```
+
+You will need to add an appservice registration file in the future,
+but it is not important for now.
+
+
+And then to run the homeserver:
+
+```bash
+docker run -d --name synapse \
+    -v ~/slack-bridge-env/synapse:/data \
+    -p 8008:8008 \
+    matrixdotorg/synapse:v1.3.1-py3
+```
+
+These instructions are based off those given in https://hub.docker.com/r/matrixdotorg/synapse.
 
-Largely to setup Synapse, you can follow https://hub.docker.com/r/matrixdotorg/synapse and just ensure your data directory points to `~/slack-bridge-env/synapse`.  
-You will want to make sure your server name is something that routes to your local box. I tend to use the devbox hostname, but `localhost` is also sufficent.  
-You should enable registration in the `homeserver.yaml` to create a testing user.  
-You will need to add an appservice registration file in the future, but it is not imprtant for now.
 
-### Setting up Riot
+### 2. Setting up Riot
 
 Setting up Riot is also quite straightforward:
 
-Create a new config called `~/slack-bridge-env/riot-config.json` with the contents needed to set defaults to your local homeserver.
+Create a new config called `~/slack-bridge-env/riot-config.json` with the contents
+needed to set defaults to your local homeserver.
 
 As an example:
 
@@ -60,11 +102,13 @@ As an example:
 }
 ```
 
-Finally, run `docker run -v /home/will/git/scalar-env/riot-config.json:/app/config.json -p 8080:80 vectorim/riot-web` to start your Riot instance. You should be able to register a new user on your local synapse instance through Riot.
+Finally, run `docker run -v /home/will/git/scalar-env/riot-config.json:/app/config.json -p 8080:80 vectorim/riot-web`
+to start your Riot instance. You should be able to register a new user on your
+local synapse instance through Riot.
 
-### Setting up the bridge postgres
+### 3. Setting up the bridge with PostgreSQL
 
-Setting up the postgres instance for the bridge is also quite easy.
+You can setup PostgreSQL in docker.
 
 ```bash
 docker run -d --name slackpg -p 59999:5432 -e POSTGRES_PASSWORD=pass postgres
@@ -73,17 +117,16 @@ docker run -d --name slackpg -p 59999:5432 -e POSTGRES_PASSWORD=pass postgres
 You should also create a new database in preparation for using the bridge
 
 ```bash
-sudo apt install postgresql-client # Ensure you have psql installed
 psql -h localhost -U postgres -W postgres
 ```
 
-And then on the postgres shell
+And then on the postgres shell:
 
 ```sql
 CREATE DATABASE slack
 ```
 
-### Setting up the bridge
+### 4. Setting up the bridge
 
 Clone the bridge repo to a place of your choice, again for simplicity we will
 use the env directory. Make sure you clone your **fork** and not the upstream repo.
@@ -101,9 +144,12 @@ The steps above should make sure you are running the latest development version
 and have built the typescript. To ensure that it's all working, you can run
 `npm test` which will run the unit and integration tests. 
 
-You can follow the instructions in the [README](../README.md) to generate and update the registration file, as well as creating a testing Slack app and workspace. You should enable RTM support in the config, as Slack will not be able to push events to your local bridge.
+You can follow the instructions in the [README](../README.md), under the to generate and update the
+registration file. You should follow the "Recommended - Events API" to setup a Slack app. This guide
+strongly recommends using the RTM API for local development as it does not require a webserver.
 
-Make sure that you copy the generated registration file to `~/slack-bridge-env/synapse` and add an entry for it in the `homeserver.yaml` before starting the synapse container.
+Make sure that you copy the generated registration file to `~/slack-bridge-env/synapse` and
+add an entry for it in the `homeserver.yaml` before starting the synapse container.
 
 ## Making changes
 
@@ -112,10 +158,13 @@ Whenever you want to make changes to the codebase, you must:
 ```bash
 git fetch matrix-org
 git checkout matrix-org/develop
-git checkout -b yourfeaturname
+git checkout -b yourfeaturename
 npm i
 ```
 
-You should always work within the `src` directory. It is helpful to have a code editor setup with linting enabled so you can see mistakes as you work. Always remember to run `npm run build` before commiting or testing so that you know the latest changes work.  
+You should always work within the `src` directory. It is helpful to have a code editor setup
+with linting enabled so you can see mistakes as you work. Always remember to run `npm run build`
+before commiting or testing so that you know the latest changes work.  
 
-Before commiting your work, ensure that the tests pass locally with `npm test`. If you are making changes to packages, ensure that `package-lock.json` is included in the commit.
+Before commiting your work, ensure that the tests pass locally with `npm test`. If you are making
+changes to packages, ensure that `package-lock.json` is included in the commit.