deploy: ecef741add

develop/development/contributing_guide.html

@@ -177,16 +177,21 @@ git checkout develop
 <p>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.</p>
 <h1 id="4-install-the-dependencies"><a class="header" href="#4-install-the-dependencies">4. Install the dependencies</a></h1>
-<p>Once you have installed Python 3 and added the source, please open a terminal and
+<p>Synapse uses the <a href="https://python-poetry.org/">poetry</a> project to manage its dependencies
-setup a <em>virtualenv</em>, as follows:</p>
+and development environment. Once you have installed Python 3 and added the
-<pre><code class="language-sh">cd path/where/you/have/cloned/the/repository
+source, you should install <code>poetry</code>.
-python3 -m venv ./env
+Of their installation methods, we recommend
-source ./env/bin/activate
+<a href="https://python-poetry.org/docs/#installing-with-pipx">installing <code>poetry</code> using <code>pipx</code></a>,</p>
-pip install wheel
+<pre><code class="language-shell">pip install --user pipx
-pip install -e &quot;.[all,dev]&quot;
+pipx install poetry
-pip install tox
 </code></pre>
-<p>This will install the developer dependencies for the project.</p>
+<p>but see poetry's <a href="https://python-poetry.org/docs/#installation">installation instructions</a>
+for other installation methods.</p>
+<p>Next, open a terminal and install dependencies as follows:</p>
+<pre><code class="language-sh">cd path/where/you/have/cloned/the/repository
+poetry install --extras all
+</code></pre>
+<p>This will install the runtime and developer dependencies for the project.</p>
 <h1 id="5-get-in-touch"><a class="header" href="#5-get-in-touch">5. Get in touch.</a></h1>
 <p>Join our developer community on Matrix: <a href="https://matrix.to/#/#synapse-dev:matrix.org">#synapse-dev:matrix.org</a>!</p>
 <h1 id="6-pick-an-issue"><a class="header" href="#6-pick-an-issue">6. Pick an issue.</a></h1>
@@ -226,37 +231,32 @@ want to test your code.</p>
 <li>ensure that your code follows the coding style adopted by the project;</li>
 <li>catch a number of errors in your code.</li>
 </ul>
-<p>The linter takes no time at all to run as soon as you've <a href="#4-install-the-dependencies">downloaded the dependencies into your python virtual environment</a>.</p>
+<p>The linter takes no time at all to run as soon as you've <a href="#4-install-the-dependencies">downloaded the dependencies</a>.</p>
-<pre><code class="language-sh">source ./env/bin/activate
+<pre><code class="language-sh">poetry run ./scripts-dev/lint.sh
-./scripts-dev/lint.sh
 </code></pre>
 <p>Note that this script <em>will modify your files</em> to fix styling errors.
 Make sure that you have saved all your files.</p>
 <p>If you wish to restrict the linters to only the files changed since the last commit
 (much faster!), you can instead run:</p>
-<pre><code class="language-sh">source ./env/bin/activate
+<pre><code class="language-sh">poetry run ./scripts-dev/lint.sh -d
-./scripts-dev/lint.sh -d
 </code></pre>
 <p>Or if you know exactly which files you wish to lint, you can instead run:</p>
-<pre><code class="language-sh">source ./env/bin/activate
+<pre><code class="language-sh">poetry run ./scripts-dev/lint.sh path/to/file1.py path/to/file2.py path/to/folder
-./scripts-dev/lint.sh path/to/file1.py path/to/file2.py path/to/folder
 </code></pre>
 <h2 id="run-the-unit-tests-twisted-trial"><a class="header" href="#run-the-unit-tests-twisted-trial">Run the unit tests (Twisted trial).</a></h2>
 <p>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.</p>
-<pre><code class="language-sh">source ./env/bin/activate
+<pre><code class="language-sh">poetry run trial tests
-trial tests
 </code></pre>
 <p>If you wish to only run <em>some</em> unit tests, you may specify
 another module instead of <code>tests</code> - or a test class or a method:</p>
-<pre><code class="language-sh">source ./env/bin/activate
+<pre><code class="language-sh">poetry run trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_invite
-trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_invite
 </code></pre>
 <p>If your tests fail, you may wish to look at the logs (the default log level is <code>ERROR</code>):</p>
 <pre><code class="language-sh">less _trial_temp/test.log
 </code></pre>
 <p>To increase the log level for the tests, set <code>SYNAPSE_TEST_LOG_LEVEL</code>:</p>
-<pre><code class="language-sh">SYNAPSE_TEST_LOG_LEVEL=DEBUG trial tests
+<pre><code class="language-sh">SYNAPSE_TEST_LOG_LEVEL=DEBUG poetry run trial tests
 </code></pre>
 <p>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 <code>SYNAPSE_TEST_PERSIST_SQLITE_DB</code> environment variable. Doing so will cause the
 database state to be stored in a file named <code>test.db</code> under the trial process'
 working directory. Typically, this ends up being <code>_trial_temp/test.db</code>. For example:</p>
-<pre><code class="language-sh">SYNAPSE_TEST_PERSIST_SQLITE_DB=1 trial tests
+<pre><code class="language-sh">SYNAPSE_TEST_PERSIST_SQLITE_DB=1 poetry run trial tests
 </code></pre>
 <p>The database file can then be inspected with:</p>
 <pre><code class="language-sh">sqlite3 _trial_temp/test.db

develop/print.html

@@ -1547,25 +1547,33 @@ packages</a>, you will need to follow the
 normal process for upgrading those packages.</p>
 </li>
 <li>
-<p>If Synapse was installed from source, then:</p>
-<ol>
-<li>
-<p>Activate the virtualenv before upgrading. For example, if
-Synapse is installed in a virtualenv in <code>~/synapse/env</code> then
-run:</p>
-<pre><code class="language-bash">source ~/synapse/env/bin/activate
-</code></pre>
-</li>
-<li>
 <p>If Synapse was installed using pip then upgrade to the latest
 version by running:</p>
 <pre><code class="language-bash">pip install --upgrade matrix-synapse
 </code></pre>
-<p>If Synapse was installed using git then upgrade to the latest
+</li>
-version by running:</p>
+<li>
-<pre><code class="language-bash">git pull
+<p>If Synapse was installed from source, then:</p>
+<ol>
+<li>
+<p>Obtain the latest version of the source code. Git users can run
+<code>git pull</code> to do this.</p>
+</li>
+<li>
+<p>If you're running Synapse in a virtualenv, make sure to activate it before
+upgrading. For example, if Synapse is installed in a virtualenv in <code>~/synapse/env</code> then
+run:</p>
+<pre><code class="language-bash">source ~/synapse/env/bin/activate
 pip install --upgrade .
 </code></pre>
+<p>Include any relevant extras between square brackets, e.g. <code>pip install --upgrade &quot;.[postgres,oidc]&quot;</code>.</p>
+</li>
+<li>
+<p>If you're using <code>poetry</code> to manage a Synapse installation, run:</p>
+<pre><code class="language-bash">poetry install
+</code></pre>
+<p>Include any relevant extras with <code>--extras</code>, e.g. <code>poetry install --extras postgres --extras oidc</code>.
+It's probably easiest to run <code>poetry install --extras all</code>.</p>
 </li>
 <li>
 <p>Restart Synapse:</p>
@@ -16061,16 +16069,21 @@ git checkout develop
 <p>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.</p>
 <h1 id="4-install-the-dependencies"><a class="header" href="#4-install-the-dependencies">4. Install the dependencies</a></h1>
-<p>Once you have installed Python 3 and added the source, please open a terminal and
+<p>Synapse uses the <a href="https://python-poetry.org/">poetry</a> project to manage its dependencies
-setup a <em>virtualenv</em>, as follows:</p>
+and development environment. Once you have installed Python 3 and added the
-<pre><code class="language-sh">cd path/where/you/have/cloned/the/repository
+source, you should install <code>poetry</code>.
-python3 -m venv ./env
+Of their installation methods, we recommend
-source ./env/bin/activate
+<a href="https://python-poetry.org/docs/#installing-with-pipx">installing <code>poetry</code> using <code>pipx</code></a>,</p>
-pip install wheel
+<pre><code class="language-shell">pip install --user pipx
-pip install -e &quot;.[all,dev]&quot;
+pipx install poetry
-pip install tox
 </code></pre>
-<p>This will install the developer dependencies for the project.</p>
+<p>but see poetry's <a href="https://python-poetry.org/docs/#installation">installation instructions</a>
+for other installation methods.</p>
+<p>Next, open a terminal and install dependencies as follows:</p>
+<pre><code class="language-sh">cd path/where/you/have/cloned/the/repository
+poetry install --extras all
+</code></pre>
+<p>This will install the runtime and developer dependencies for the project.</p>
 <h1 id="5-get-in-touch"><a class="header" href="#5-get-in-touch">5. Get in touch.</a></h1>
 <p>Join our developer community on Matrix: <a href="https://matrix.to/#/#synapse-dev:matrix.org">#synapse-dev:matrix.org</a>!</p>
 <h1 id="6-pick-an-issue"><a class="header" href="#6-pick-an-issue">6. Pick an issue.</a></h1>
@@ -16110,37 +16123,32 @@ want to test your code.</p>
 <li>ensure that your code follows the coding style adopted by the project;</li>
 <li>catch a number of errors in your code.</li>
 </ul>
-<p>The linter takes no time at all to run as soon as you've <a href="development/contributing_guide.html#4-install-the-dependencies">downloaded the dependencies into your python virtual environment</a>.</p>
+<p>The linter takes no time at all to run as soon as you've <a href="development/contributing_guide.html#4-install-the-dependencies">downloaded the dependencies</a>.</p>
-<pre><code class="language-sh">source ./env/bin/activate
+<pre><code class="language-sh">poetry run ./scripts-dev/lint.sh
-./scripts-dev/lint.sh
 </code></pre>
 <p>Note that this script <em>will modify your files</em> to fix styling errors.
 Make sure that you have saved all your files.</p>
 <p>If you wish to restrict the linters to only the files changed since the last commit
 (much faster!), you can instead run:</p>
-<pre><code class="language-sh">source ./env/bin/activate
+<pre><code class="language-sh">poetry run ./scripts-dev/lint.sh -d
-./scripts-dev/lint.sh -d
 </code></pre>
 <p>Or if you know exactly which files you wish to lint, you can instead run:</p>
-<pre><code class="language-sh">source ./env/bin/activate
+<pre><code class="language-sh">poetry run ./scripts-dev/lint.sh path/to/file1.py path/to/file2.py path/to/folder
-./scripts-dev/lint.sh path/to/file1.py path/to/file2.py path/to/folder
 </code></pre>
 <h2 id="run-the-unit-tests-twisted-trial"><a class="header" href="#run-the-unit-tests-twisted-trial">Run the unit tests (Twisted trial).</a></h2>
 <p>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.</p>
-<pre><code class="language-sh">source ./env/bin/activate
+<pre><code class="language-sh">poetry run trial tests
-trial tests
 </code></pre>
 <p>If you wish to only run <em>some</em> unit tests, you may specify
 another module instead of <code>tests</code> - or a test class or a method:</p>
-<pre><code class="language-sh">source ./env/bin/activate
+<pre><code class="language-sh">poetry run trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_invite
-trial tests.rest.admin.test_room tests.handlers.test_admin.ExfiltrateData.test_invite
 </code></pre>
 <p>If your tests fail, you may wish to look at the logs (the default log level is <code>ERROR</code>):</p>
 <pre><code class="language-sh">less _trial_temp/test.log
 </code></pre>
 <p>To increase the log level for the tests, set <code>SYNAPSE_TEST_LOG_LEVEL</code>:</p>
-<pre><code class="language-sh">SYNAPSE_TEST_LOG_LEVEL=DEBUG trial tests
+<pre><code class="language-sh">SYNAPSE_TEST_LOG_LEVEL=DEBUG poetry run trial tests
 </code></pre>
 <p>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
@@ -16148,7 +16156,7 @@ review database state during and after running tests. This can be done by settin
 the <code>SYNAPSE_TEST_PERSIST_SQLITE_DB</code> environment variable. Doing so will cause the
 database state to be stored in a file named <code>test.db</code> under the trial process'
 working directory. Typically, this ends up being <code>_trial_temp/test.db</code>. For example:</p>
-<pre><code class="language-sh">SYNAPSE_TEST_PERSIST_SQLITE_DB=1 trial tests
+<pre><code class="language-sh">SYNAPSE_TEST_PERSIST_SQLITE_DB=1 poetry run trial tests
 </code></pre>
 <p>The database file can then be inspected with:</p>
 <pre><code class="language-sh">sqlite3 _trial_temp/test.db

develop/upgrade.html

@@ -167,25 +167,33 @@ packages</a>, you will need to follow the
 normal process for upgrading those packages.</p>
 </li>
 <li>
-<p>If Synapse was installed from source, then:</p>
-<ol>
-<li>
-<p>Activate the virtualenv before upgrading. For example, if
-Synapse is installed in a virtualenv in <code>~/synapse/env</code> then
-run:</p>
-<pre><code class="language-bash">source ~/synapse/env/bin/activate
-</code></pre>
-</li>
-<li>
 <p>If Synapse was installed using pip then upgrade to the latest
 version by running:</p>
 <pre><code class="language-bash">pip install --upgrade matrix-synapse
 </code></pre>
-<p>If Synapse was installed using git then upgrade to the latest
+</li>
-version by running:</p>
+<li>
-<pre><code class="language-bash">git pull
+<p>If Synapse was installed from source, then:</p>
+<ol>
+<li>
+<p>Obtain the latest version of the source code. Git users can run
+<code>git pull</code> to do this.</p>
+</li>
+<li>
+<p>If you're running Synapse in a virtualenv, make sure to activate it before
+upgrading. For example, if Synapse is installed in a virtualenv in <code>~/synapse/env</code> then
+run:</p>
+<pre><code class="language-bash">source ~/synapse/env/bin/activate
 pip install --upgrade .
 </code></pre>
+<p>Include any relevant extras between square brackets, e.g. <code>pip install --upgrade &quot;.[postgres,oidc]&quot;</code>.</p>
+</li>
+<li>
+<p>If you're using <code>poetry</code> to manage a Synapse installation, run:</p>
+<pre><code class="language-bash">poetry install
+</code></pre>
+<p>Include any relevant extras with <code>--extras</code>, e.g. <code>poetry install --extras postgres --extras oidc</code>.
+It's probably easiest to run <code>poetry install --extras all</code>.</p>
 </li>
 <li>
 <p>Restart Synapse:</p>