Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Development guide #215

Open
wants to merge 8 commits into
base: develop
Choose a base branch
from
Open

Development guide #215

wants to merge 8 commits into from

Conversation

Half-Shot
Copy link
Contributor

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.

Copy link
Member

@benparsons benparsons left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm for the text.

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

Copy link
Member

@turt2live turt2live left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have opinions (no surprise, but sorry)

docs/development_guide.md Outdated Show resolved Hide resolved
docs/development_guide.md Outdated Show resolved Hide resolved

### Prereqs

Ensure at the minimum you have installed:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not if we're doing it in a container.


## Setting up your environment

This section explains how to setup Synapse, Riot and the Slack bridge for local development.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

docs/development_guide.md Outdated Show resolved Hide resolved

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

docs/development_guide.md Outdated Show resolved Hide resolved
docs/development_guide.md Outdated Show resolved Hide resolved
docs/development_guide.md Outdated Show resolved Hide resolved
docs/development_guide.md Outdated Show resolved Hide resolved

### Setting up 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`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

docs/development_guide.md Outdated Show resolved Hide resolved
docs/development_guide.md Outdated Show resolved Hide resolved
docs/development_guide.md Outdated Show resolved Hide resolved
Copy link
Member

@benparsons benparsons left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

docs/development_guide.md Outdated Show resolved Hide resolved
docs/development_guide.md Outdated Show resolved Hide resolved
[![#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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@turt2live turt2live left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My largest concern is #215 (comment)

@Cadair Cadair removed their request for review February 7, 2020 12:26
@AndrewFerr AndrewFerr requested a review from a team as a code owner November 15, 2022 07:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants