Development guide

.buildkite/pipeline.yml

@@ -37,7 +37,7 @@ steps:
     branches: "!master !develop !release-*"
     command:
       - "python3 -m pip install towncrier"
-      - "python3 -m towncrier.check"
+      - "python3 -m towncrier.check --compare-with=origin/develop"
     plugins:
       - docker#v3.0.1:
           image: "python:3.6"

README.md

@@ -3,6 +3,14 @@ A Matrix <--> Slack bridge
 
 This bridge allows you to connect Slack channels to Matrix rooms.
 
+Development
+-----------
+
+[![#slack:half-shot.uk](https://img.shields.io/matrix/slack:half-shot.uk.svg?server_fqdn=matrix.half-shot.uk&label=%23slack:half-shot.uk&logo=matrix)](https://matrix.to/#/#slack:half-shot.uk)
+
+If you want to help out, please give our helpful [Development Guide](./docs/development_guide.md)
+a read. It covers all you need to know to get hacking on the bridge.
+
 Installation
 ------------
 
@@ -101,23 +109,40 @@ and bot users. This allows you to link as many channels as you would like with o
 3. Click on `bot users` and add a new bot user. We will use this account to bridge the
    the rooms.
 
-4. Click on `Event Subscriptions` and enable them. At this point, the bridge needs to be
-   started as Slack will do some verification of the request rul. The request url should be
-   `https://$HOST:$SLACK_PORT"`. Then add the following events and save:
+4. Click on `Event Subscriptions` and enable them. 
+
+   1. You will need to decide on using either the **RTM API** or the **Events API**.  
+      The RTM API is recommended because it does not require you to setup scopes or open ports
+      to a webserver like the Events API.  
+      Events API provisioning is forwards compatible with the RTM API and if enabled in the config,
+      RTM is used by default.
+      The RTM API uses websockets and will pull information from Slack, whereas the Events API will
+      push informaton to the bridge over HTTP.
+
+   2. If you want to use the RTM API, ensure that you have enabled RTM support in the
+      config file. And then put your feet up, you are done.
+
+   3. If you want to use the Events API, follow these steps:
 
-   Bot User Events:
+      The bridge needs to be started as Slack will do some verification of the request url. The request url should be `https://$HOST:$SLACK_PORT"`. Then add the following events to "Subscribe to Bot Events" and save:
 
-       - team_domain_change
-       - message.channels
-       - chat:write:bot
-       - message.groups (if you want to bridge private channels)
-       - users:read
-       - team.info
+         - team_domain_change
+         - message.channels
+         - reaction_added
+         - reaction_removed
 
-5. Skip this step if you do not want to bridge files.
-   Click on `OAuth & Permissions` and add the following scopes:
+5. Click on `OAuth & Permissions` and add the following scopes:
 
-   - files:write:user
+   - files:read (So the bot may upload files to Matrix)
+   - files:write:user (Upload files from Matrix)
+   - users:read (Profile information on users)
+   - team:read (Get basic information about the workspace)
+   - chat:write:bot (Write messages as the bridge bot)
+   - reactions:write (Add/remove reactions on Slack)
+
+   The following are needed if you plan to integrate the bridge with an Integration Manager:
+
+   - channels:read (Used to fetch information about public channels on the workspace)
 
    Note: any media uploaded to matrix is currently accessible by anyone who knows the url.
    In order to make Slack files visible to matrix users, this bridge will make Slack files
@@ -126,9 +151,8 @@ and bot users. This allows you to link as many channels as you would like with o
    posted in private channels. See [MSC701](https://github.com/matrix-org/matrix-doc/issues/701)
    for details.
 
-6. Click on `Install App` and `Install App to Workspace`. Note the access tokens show.
-   You will need the `Bot User OAuth Access Token` and if you want to bridge files, the
-   `OAuth Access Token` whenever you link a room.
+6. Click on `Install App` and `Install App to Workspace`. Note the access token shown.
+   You will need the `OAuth Access Token` whenever you link a room.
 
 7. For each channel you would like to bridge, perform the following steps:
 
@@ -147,16 +171,9 @@ and bot users. This allows you to link as many channels as you would like with o
    3. Issue a ``link`` command in the administration control room with these
       collected values as arguments:
 
-      with file bridging:
-
          ```
          link --channel_id CHANNELID --room !the-matrix:room.id --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx --slack_user_token xoxp-xxxxxxxx-xxxxxxxxx-xxxxxxxx-xxxxxxxx
          ```
-      without file bridging:
-
-         ```
-         link --channel_id CHANNELID --room !the-matrix:room.id --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
-         ```
 
       These arguments can be shortened to single-letter forms:
 

changelog.d/215.doc

@@ -0,0 +1 @@
+Added docs/development_guide.md to aid new users hacking on the bridge.

docs/development_guide.md

@@ -0,0 +1,170 @@
+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.
+
+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.
+
+### 0. Prerequisites 
+
+Ensure at the minimum you have installed:
+
+- 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`
+
+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
+```
+
+### 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.
+
+
+### 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.
+
+As an example:
+
+```json
+{
+    "default_server_config": {
+        "m.homeserver": {
+            "base_url": "http://localhost:8008",
+            "server_name": "localhost"
+        }
+    },
+    "disable_custom_urls": false,
+    "disable_guests": false,
+    "disable_login_language_selector": false,
+    "disable_3pid_login": false,
+    "brand": "Riot",
+    "defaultCountryCode": "GB",
+    "showLabsSettings": false,
+    "default_federate": true,
+    "default_theme": "light"
+}
+```
+
+Finally, run `docker run -d --name riot -v ~/slack-bridge-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.
+
+### 3. Setting up the bridge with PostgreSQL
+
+You can setup PostgreSQL in docker.
+
+```bash
+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
+psql -h localhost -p 59999 -U postgres -W postgres
+```
+
+And then on the postgres shell:
+
+```sql
+CREATE DATABASE slack
+```
+
+### 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.
+
+```bash
+git clone [email protected]:your-github-username/matrix-appservice-slack.git
+cd matrix-appservice-slack
+git remote add matrix-org [email protected]:matrix-org/matrix-appservice-slack.git
+git checkout matrix-org/develop # Always base your changes off matrix-org/develop
+npm i
+npm run build
+```
+
+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), 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.
+
+## Making changes
+
+Whenever you want to make changes to the codebase, you must:
+
+```bash
+git fetch matrix-org
+git checkout matrix-org/develop
+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.  
+
+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.