Batch of suggestsion from Brendan, part 1

Co-authored-by: Brendan Abolivier <babolivier@matrix.org>

.ci/scripts/test_old_deps.sh

@@ -20,10 +20,10 @@ export LANG="C.UTF-8"
 # Prevent virtualenv from auto-updating pip to an incompatible version
 export VIRTUALENV_NO_DOWNLOAD=1
 
-# I'd prefer to use something like this
+# TODO: in the future, we could use an implementation of
 #   https://github.com/python-poetry/poetry/issues/3527
 #   https://github.com/pypa/pip/issues/8085
-# rather than this sed script. But that's an Opinion.
+# to select the lowest possible versions, rather than resorting to this sed script.
 
 # patch the project definitions in-place
 # replace all lower bounds with exact bounds

.gitignore

@@ -15,8 +15,7 @@ _trial_temp*/
 .DS_Store
 __pycache__/
 
-# We do want the poetry lockfile. TODO: is there a good reason for ignoring
-# '*.lock' above? If not, let's nuke it.
+# We do want the poetry lockfile. Ignoring '*.lock' above seems to ignore tox and trial lock files.
 !poetry.lock
 
 # stuff that is likely to exist when you run a server locally

README.rst

@@ -300,7 +300,7 @@ environment using [poetry](https://python-poetry.org/). First, install poetry. W
     pipx install poetry
 
 but see the `poetry installation docs <https://python-poetry.org/docs/#installation>`_
-for more details. Then ask poetry to create a virtualenvironment from the project
+for more details. Then ask poetry to create a virtual environment from the project
 and install Synapse's dependencies::
 
     poetry install --extras "all test"

docker/Dockerfile

@@ -26,9 +26,9 @@ FROM docker.io/python:${PYTHON_VERSION}-slim as base
 # poetry-managed environment in a docker image. For a while,
 # `poetry export | pip install -r /dev/stdin` seemed plausible but is limited by bugs
 # in `poetry export` whose fixes (scheduled for poetry 1.2) have yet to be released.
-# The best references I could find are
+# This is inspired from:
 #     https://github.com/python-poetry/poetry/discussions/1879#discussioncomment-216865
-#     https://stackoverflow.com/questions/53835198/integrating-python-poetry-with-docker?answertab=scoredesc#tab-top
+#     https://stackoverflow.com/questions/53835198/integrating-python-poetry-with-docker?answertab=scoredesc
 FROM base as builder
 
 # RUN --mount is specific to buildkit and is documented at
@@ -60,7 +60,7 @@ RUN \
 
 WORKDIR /synapse
 
-# Copy just what we need to poetry install
+# Copy just what we need to run `poetry install`
 COPY pyproject.toml poetry.lock README.rst /synapse/
 
 # Install to the Python installation which hosts `pip`. In this case, it's the system