Development guide

[Half-Shot]

Fixes #213

This should address the need for a dev guide so new developers can hack on the bridge. It's currently drafted and needs proofreading.

[benparsons]

lgtm for the text.

nb I have not actually followed the instructions yet, might come back with comments/changes when I do

[turt2live]

I have opinions (no surprise, but sorry)

[turt2live]

Don't we also need python if we're explaining how to set up Synapse? Ignoring the fact that I disagree with us telling people how to set up Synapse of course.

[Half-Shot]

Not if we're doing it in a container.

[turt2live]

Synapse and Riot should have their own documentation in their own projects. We run the risk of it being outdated very quickly here.

[Half-Shot]

We've made a conscious choice to make the guide follow-able without leaving the project. The steps are sufficiently noninvasive that they should work for the near future. If the steps do change, then we would update this guide accordingly.

Part of the reason for the guide is to be a one-stop shop on how to setup a developers environment, rather than spending time learning about each project.

[Half-Shot]

We've made a conscious choice to make the guide follow-able without leaving the project. The steps are sufficiently noninvasive that they should work for the near future. If the steps do change, then we would update this guide accordingly.

Part of the reason for the guide is to be a one-stop shop on how to setup a developers environment, rather than spending time learning about each project.

[turt2live]

I seriously disagree with that decision. For one, I'm not reviewing the same blobs of text over and over, and I'm sure not expecting that anyone goes around to update all the install guides for all the projects.

Pointing to an existing guide has a two major benefits as far as I'm concerned:

• The project retains control over which installation method is preferred. The upstream projects (namely Riot and Synapse) are likely to want to change their preferred installation methods, particularly Riot in the nearish future. By nature of the relationship between the bridge team and the auxiliary projects, the auxiliary projects would need to inform the bridge team that their docs are now outdated, leading to a lot of suddenly outdated documentation.
• The steps are in a single canonical location. There's several bridges and other projects which would need this same guide: by rewriting the same words over and over, we're duplicating information. Pointing to the project's own guides means we don't have to repeat it.

In short: please let's not make more work for everyone.

[benparsons]

My problem with keeping the setup instructions in their own home is that the specific requirements for this purpose (setup to create a dev environment for hacking on the Slack bridge) are not made clear by the instructions for those projects. The way it is right now - with very minimal steps needed for each case, plus a link to the canonical sources is much more effective. See this example: https://github.com/matrix-org/matrix-appservice-slack/pull/215/files#diff-c570356b15a684fa012ea55e4347e51bR73, which I found very readable.

What's currently not readable is having the dev setup guide link to the README and DATASTORES pages, which are much more general pages that go beyond the scope of what's needed for a dev environment setup.

It may be more work to maintain these duplicated blobs (I'm not sure how much more work it would be), but right now it's too complex to get started hacking on this project, so more streamlined docs are neeeded.

[turt2live]

Setting up a Synapse server for development or for public is largely the same, barring a few config changes. I seriously don't see a problem with saying "Install Synapse as per [their instructions] then add the appservice's registration file to the config. If you're not sure how to do that, [click here]". Both links would (and should) be to the Synapse repository.

[turt2live]

Suggested change

	### Setting up the bridge postgres
	### Setting up the bridge with PostgreSQL

[turt2live]

also might be relevant to link to digital ocean's managed databases thing. It's a fairly inexpensive option for people doing lots of development

[Half-Shot]

I think it's probably out of scope for a fairly restricted guide to get yourself writing simple PRs. The intention is for users to expand their knowledge by themselves after they have an environment set up, so perhaps it can be part of further reading.

[benparsons]

The docker commands in the hub.docker.com docs need to be changed. I recommend including them explicitly here with the needed changes, for example:

docker run -it --rm \
    -v ~/slack-bridge-env/synapse:/data \
    -e SYNAPSE_SERVER_NAME=localhost \
    -e SYNAPSE_REPORT_STATS=no \
    matrixdotorg/synapse:latest generate

docker run -d --name synapse \
    -v ~/slack-bridge-env/synapse:/data \
    -p 8008:8008 \
    matrixdotorg/synapse:latest

[benparsons]

I think there needs to be a lot more changes in README and DATASTOREs to help with getting a dev environment working.

Starting to think that for development it would be preferable to move content from those to files into the new development_guide file, where you can be more specific about what do do on a local environment.

[benparsons]

Can we be more explicit about the Setup steps and how they relate to getting a dev environment working? Eg port selection could be specific, the config file "you may wish to copy and edit as appropriate" - this can be really prescriptive for dev environment rather than deployment.

[turt2live]

My largest concern is #215 (comment)