This commit is contained in:
DMRobertson 2022-04-20 14:18:55 +00:00
parent 963ebb0428
commit 570ffadd0a
5 changed files with 88 additions and 72 deletions

View file

@ -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 <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> 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> <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> </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> <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> <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> <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>ensure that your code follows the coding style adopted by the project;</li>
<li>catch a number of errors in your code.</li> <li>catch a number of errors in your code.</li>
</ul> </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> </code></pre>
<p>Note that this script <em>will modify your files</em> to fix styling errors. <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> 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 <p>If you wish to restrict the linters to only the files changed since the last commit
(much faster!), you can instead run:</p> (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> </code></pre>
<p>Or if you know exactly which files you wish to lint, you can instead run:</p> <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> </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> <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 <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> 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> </code></pre>
<p>If you wish to only run <em>some</em> unit tests, you may specify <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> 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> </code></pre>
<p>If your tests fail, you may wish to look at the logs (the default log level is <code>ERROR</code>):</p> <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 <pre><code class="language-sh">less _trial_temp/test.log
</code></pre> </code></pre>
<p>To increase the log level for the tests, set <code>SYNAPSE_TEST_LOG_LEVEL</code>:</p> <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> </code></pre>
<p>By default, tests will use an in-memory SQLite database for test data. For additional <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 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 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' 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> 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> </code></pre>
<p>The database file can then be inspected with:</p> <p>The database file can then be inspected with:</p>
<pre><code class="language-sh">sqlite3 _trial_temp/test.db <pre><code class="language-sh">sqlite3 _trial_temp/test.db

View file

@ -1547,25 +1547,33 @@ packages</a>, you will need to follow the
normal process for upgrading those packages.</p> normal process for upgrading those packages.</p>
</li> </li>
<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 <p>If Synapse was installed using pip then upgrade to the latest
version by running:</p> version by running:</p>
<pre><code class="language-bash">pip install --upgrade matrix-synapse <pre><code class="language-bash">pip install --upgrade matrix-synapse
</code></pre> </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 . pip install --upgrade .
</code></pre> </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>
<li> <li>
<p>Restart Synapse:</p> <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 <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> 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> <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> </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> <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> <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> <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>ensure that your code follows the coding style adopted by the project;</li>
<li>catch a number of errors in your code.</li> <li>catch a number of errors in your code.</li>
</ul> </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> </code></pre>
<p>Note that this script <em>will modify your files</em> to fix styling errors. <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> 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 <p>If you wish to restrict the linters to only the files changed since the last commit
(much faster!), you can instead run:</p> (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> </code></pre>
<p>Or if you know exactly which files you wish to lint, you can instead run:</p> <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> </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> <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 <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> 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> </code></pre>
<p>If you wish to only run <em>some</em> unit tests, you may specify <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> 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> </code></pre>
<p>If your tests fail, you may wish to look at the logs (the default log level is <code>ERROR</code>):</p> <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 <pre><code class="language-sh">less _trial_temp/test.log
</code></pre> </code></pre>
<p>To increase the log level for the tests, set <code>SYNAPSE_TEST_LOG_LEVEL</code>:</p> <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> </code></pre>
<p>By default, tests will use an in-memory SQLite database for test data. For additional <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 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 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' 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> 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> </code></pre>
<p>The database file can then be inspected with:</p> <p>The database file can then be inspected with:</p>
<pre><code class="language-sh">sqlite3 _trial_temp/test.db <pre><code class="language-sh">sqlite3 _trial_temp/test.db

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

View file

@ -167,25 +167,33 @@ packages</a>, you will need to follow the
normal process for upgrading those packages.</p> normal process for upgrading those packages.</p>
</li> </li>
<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 <p>If Synapse was installed using pip then upgrade to the latest
version by running:</p> version by running:</p>
<pre><code class="language-bash">pip install --upgrade matrix-synapse <pre><code class="language-bash">pip install --upgrade matrix-synapse
</code></pre> </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 . pip install --upgrade .
</code></pre> </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>
<li> <li>
<p>Restart Synapse:</p> <p>Restart Synapse:</p>