-
Notifications
You must be signed in to change notification settings - Fork 72
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
base: develop
Are you sure you want to change the base?
Development guide #215
Conversation
b1dce75
to
cd589dd
Compare
There was a problem hiding this 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
d87548c
to
38c888c
Compare
There was a problem hiding this 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)
|
||
### Prereqs | ||
|
||
Ensure at the minimum you have installed: |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
docs/development_guide.md
Outdated
|
||
## Setting up your environment | ||
|
||
This section explains how to setup Synapse, Riot and the Slack bridge for local development. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
|
||
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
### Setting up the bridge postgres | |
### Setting up the bridge with PostgreSQL |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
|
||
### 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`. |
There was a problem hiding this comment.
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
9d84eb2
to
73ac807
Compare
There was a problem hiding this 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.
[![#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. |
There was a problem hiding this comment.
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.
There was a problem hiding this 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)
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.