Switch to using poetry

.github/workflows/pipeline.yml

@@ -8,22 +8,28 @@ jobs:
   check-code-style:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+
+      - name: Setup Poetry
+        uses: matrix-org/setup-python-poetry@v1
         with:
+          install-project: "false"
           python-version: "3.11"
-      - run: python -m pip install tox
-      - run: tox -e check_codestyle
+
+      - run: poetry run tox -e check_codestyle
 
   check-types-mypy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+
+      - name: Setup Poetry
+        uses: matrix-org/setup-python-poetry@v1
         with:
+          install-project: "false"
           python-version: "3.11"
-      - run: python -m pip install tox
-      - run: tox -e check_types
+
+      - run: poetry run tox -e check_types
 
   run-unit-tests:
     name: Unit tests

CONTRIBUTING.md

@@ -4,35 +4,33 @@ Everyone is welcome to contribute code to Sygnal, provided you are willing to
 license your contributions under the same license as the project itself. In
 this case, the [Apache Software License v2](LICENSE).
 
-### Create a virtualenv
+### Installing dependencies
 
 To contribute to Sygnal, ensure you have Python 3.8 or newer and then run:
 
-```bash
-python3 -m venv venv
-./venv/bin/pip install -e '.[dev]'
-```
+Sygnal uses the [poetry](https://python-poetry.org/) 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`](https://python-poetry.org/docs/#installing-with-pipx),
 
-This creates an isolated virtual Python environment ("virtualenv") just for
-use with Sygnal, then installs Sygnal along with its dependencies, and lastly
-installs a handful of useful tools
+```shell
+pip install --user pipx
+pipx install poetry
+```
 
-If you get `ConnectTimeoutError`, this is caused by slow internet whereby
-`pip` has a default time out of _15 sec_. You can specify a larger timeout
-by passing `--timeout 120` to the `pip install` command above.
+but see poetry's [installation instructions](https://python-poetry.org/docs/#installation)
+for other installation methods.
 
-Finally, activate the virtualenv by running:
+Next, open a terminal and install dependencies as follows:
 
-```bash
-source ./venv/bin/activate
+```sh
+cd path/where/you/have/cloned/the/repository
+poetry install
 ```
 
-Be sure to do this _every time_ you open a new terminal window for working on
-Sygnal. Activating the venv ensures that any Python commands you run (`pip`,
-`python`, etc.) use the versions inside your venv, and not your system Python.
-
-When you're done, you can close your terminal or run `deactivate` to disable
-the virtualenv.
+This will install the runtime and developer dependencies for the project.  Be sure to check
+that the `poetry install` step completed cleanly.
 
 ### Run the tests
 
@@ -56,6 +54,25 @@ ___________________________________ summary ___________________________________
 
 Then all is well and you're ready to work!
 
+You can also directly run the tests using poetry.
+
+```sh
+poetry run trial tests
+```
+
+You can run unit tests in parallel by specifying `-jX` argument to `trial` where `X` is the number of parallel runners you want. To use 4 cpu cores, you would run them like:
+
+```sh
+poetry run trial -j4 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:
+
+```sh
+poetry run trial tests.test_apns.ApnsTestCase.test_expected
+```
+
 ## How to contribute
 
 The preferred and easiest way to contribute changes is to fork the relevant
@@ -90,13 +107,9 @@ Many of the conventions are enforced by scripts which are run as part of the
 [continuous integration system](#continuous-integration-and-testing).
 
 To help check and fix adherence to the code style, you can run `tox`
-locally. You'll need Python 3.8 or later, and a virtual environment configured and
-active:
+locally. You'll need Python 3.8 or later:
 
 ```bash
-# Activate the virtual environment
-source ./venv/bin/activate
-
 # Run the code style check
 tox -e check_codestyle
 
@@ -114,6 +127,10 @@ Please ensure your changes match the cosmetic style of the existing project,
 and **never** mix cosmetic and functional changes in the same commit, as it
 makes it horribly hard to review otherwise.
 
+## Further information on poetry
+
+See the information provided in the [Synapse docs](https://github.com/element-hq/synapse/blob/master/docs/development/dependencies.md).
+
 ## Changelog
 
 All changes, even minor ones, need a corresponding changelog / newsfragment

RELEASING.md

@@ -1,35 +1,36 @@
 0. Consider whether this release will affect any customers, including those on
 EMS, and warn them beforehand - in case they need to upgrade quickly.
 
-1. Set a variable to the version number for convenience:
+1. Update the version number in pyproject.toml.
+2. Set a variable to the version number for convenience:
    ```sh
    ver=x.y.z
    ```
-1. Update the changelog:
+3. Update the changelog:
    ```sh
    towncrier --version=$ver
    ```
-1. Push your changes:
+4. Push your changes:
    ```sh
    git add -u && git commit -m $ver && git push
    ```
-1. Sanity-check the
+5. Sanity-check the
    [changelog](https://github.com/matrix-org/sygnal/blob/master/CHANGELOG.md)
    and update if need be.
-1. Create a signed tag for the relese:
+6. Create a signed tag for the relese:
    ```sh
    git tag -s v$ver
    ```
    Base the tag message on the changelog.
-1. Push the tag:
+7. Push the tag:
    ```sh
    git push origin tag v$ver
    ```
    Pushing a tag on GitHub will automatically trigger a build in Docker Hub and
    the resulting image will be published using the same tag as git.
-1. Create release on GH project page:
+8. Create release on GH project page:
    ```sh
    xdg-open https://github.com/matrix-org/sygnal/releases/edit/v$ver
    ```
-1. Notify #sygnal:matrix.org, #synapse-dev:matrix.org and EMS that a new
+9. Notify #sygnal:matrix.org, #synapse-dev:matrix.org and EMS that a new
    release has been published.

changelog.d/374.misc

@@ -0,0 +1 @@
+Switch over to use poetry & add lock file to version control.