From 570ffadd0a5d3743700664132fa87cac84738ca3 Mon Sep 17 00:00:00 2001
From: DMRobertson If you need help getting started with git, this is beyond the scope of the document, but you
can find many good git tutorials on the web. Once you have installed Python 3 and added the source, please open a terminal and
-setup a virtualenv, as follows: Synapse uses the poetry project to manage its dependencies
+and development environment. Once you have installed Python 3 and added the
+source, you should install but see poetry's installation instructions
+for other installation methods. Next, open a terminal and install dependencies as follows: This will install the developer dependencies for the project. This will install the runtime and developer dependencies for the project. Join our developer community on Matrix: #synapse-dev:matrix.org!4. Install the dependencies
-poetry
.
+Of their installation methods, we recommend
+installing poetry
using pipx
,
+pip install --user pipx
+pipx install poetry
+
-cd path/where/you/have/cloned/the/repository
-python3 -m venv ./env
-source ./env/bin/activate
-pip install wheel
-pip install -e ".[all,dev]"
-pip install tox
+poetry install --extras all
5. Get in touch.
6. Pick an issue.
@@ -226,37 +231,32 @@ want to test your code.
The linter takes no time at all to run as soon as you've downloaded the dependencies into your python virtual environment.
-source ./env/bin/activate
-./scripts-dev/lint.sh
+The linter takes no time at all to run as soon as you've downloaded the dependencies.
+poetry run ./scripts-dev/lint.sh
Note that this script will modify your files to fix styling errors.
Make sure that you have saved all your files.
If you wish to restrict the linters to only the files changed since the last commit
(much faster!), you can instead run:
-source ./env/bin/activate
-./scripts-dev/lint.sh -d
+poetry run ./scripts-dev/lint.sh -d
Or if you know exactly which files you wish to lint, you can instead run:
-source ./env/bin/activate
-./scripts-dev/lint.sh path/to/file1.py path/to/file2.py path/to/folder
+poetry run ./scripts-dev/lint.sh path/to/file1.py path/to/file2.py path/to/folder
Run the unit tests (Twisted trial).
The unit tests run parts of Synapse, including your changes, to see if anything
was broken. They are slower than the linters but will typically catch more errors.
-source ./env/bin/activate
-trial tests
+poetry run trial tests
If you wish to only run some unit tests, you may specify
another module instead of tests
- or a test class or a method:
-source ./env/bin/activate
-trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_invite
+poetry run trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_invite
If your tests fail, you may wish to look at the logs (the default log level is ERROR
):
less _trial_temp/test.log
To increase the log level for the tests, set SYNAPSE_TEST_LOG_LEVEL
:
-SYNAPSE_TEST_LOG_LEVEL=DEBUG trial tests
+SYNAPSE_TEST_LOG_LEVEL=DEBUG poetry run trial tests
By default, tests will use an in-memory SQLite database for test data. For additional
help with debugging, one can use an on-disk SQLite database file instead, in order to
@@ -264,7 +264,7 @@ review database state during and after running tests. This can be done by settin
the SYNAPSE_TEST_PERSIST_SQLITE_DB
environment variable. Doing so will cause the
database state to be stored in a file named test.db
under the trial process'
working directory. Typically, this ends up being _trial_temp/test.db
. For example:
-SYNAPSE_TEST_PERSIST_SQLITE_DB=1 trial tests
+SYNAPSE_TEST_PERSIST_SQLITE_DB=1 poetry run trial tests
The database file can then be inspected with:
sqlite3 _trial_temp/test.db
--
cgit 1.5.1