From 570ffadd0a5d3743700664132fa87cac84738ca3 Mon Sep 17 00:00:00 2001 From: DMRobertson Date: Wed, 20 Apr 2022 14:18:55 +0000 Subject: deploy: ecef741add0adfdd59f960e8b46503a5604303bd --- develop/development/contributing_guide.html | 42 ++++++++++++++--------------- 1 file changed, 21 insertions(+), 21 deletions(-) (limited to 'develop/development/contributing_guide.html') diff --git a/develop/development/contributing_guide.html b/develop/development/contributing_guide.html index 505b9177d7..bdcfd36ba8 100644 --- a/develop/development/contributing_guide.html +++ b/develop/development/contributing_guide.html @@ -177,16 +177,21 @@ git checkout develop

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.

4. Install the dependencies

-

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 poetry. +Of their installation methods, we recommend +installing poetry using pipx,

+
pip install --user pipx
+pipx install poetry
+
+

but see poetry's installation instructions +for other installation methods.

+

Next, open a terminal and install dependencies as follows:

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
 
-

This will install the developer dependencies for the project.

+

This will install the runtime and developer dependencies for the project.

5. Get in touch.

Join our developer community on Matrix: #synapse-dev:matrix.org!

6. Pick an issue.

@@ -226,37 +231,32 @@ want to test your code.

  • ensure that your code follows the coding style adopted by the project;
  • catch a number of errors in 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