Contribution docs improvements

matrix-org / sygnal

Sygnal: reference Push Gateway for Matrix

Apache License 2.0

166 stars 148 forks source link

Contribution docs improvements #187

Closed reivilibre closed 3 years ago

reivilibre commented 3 years ago

Could do to include:

how to create and activate a virtualenv — this is as clear as mud otherwise for new players that aren't familiar with a Python workflow
```
python3 -m venv ../venv-sygnal
. ../venv-sygnal/bin/activate
```
install Sygnal in editable mode
```
pip install -e .
```

install useful tools (note tox!)

pip install black flake8 isort mypy mypy-zope tox

callahad commented 3 years ago

The tools should potentially be extras that we could get with pip install -e .[dev] or similar... or maybe I'll convince everyone to use Poetry and then the separation is just there automatically (along with venv management)... but for now, yes.

reivilibre commented 3 years ago

@callahad I think I mentioned Pipenv some time ago and some of the team had Opinions about it, but I can't remember the specific points. If you can run it (Poetry) past the regulars and it gets their seal of approval, I think it'd be well worthwhile having something like that.

callahad commented 3 years ago

At least Patrick and I are pretty strongly against Pipenv (not sure about his reasons, but I've had Bad Experiences...)

On the flipside, I very successfully converted MDN to use Poetry (from a hand-rolled set of scripts similar to pip-tools)... so I've used Poetry in anger and I'm still pretty happy with it. And a core maintainer of Poetry is on staff at Element, now! I'd be happy with anything that gave us pinned dependencies and declarative configuration, but that's a discussion for another month.