From 2eedb349bd7596bbf2443e0feaf696103873f8ff Mon Sep 17 00:00:00 2001
From: David Robertson <davidr@element.io>
Date: Fri, 15 Jul 2022 12:35:13 +0100
Subject: [PATCH] Use and recommend poetry 1.1.14, up from 1.1.12

[1.1.14](https://github.com/python-poetry/poetry/releases/tag/1.1.14)
includes a critical bugfix needed to generate lockfiles when using PyPI
as the source of packages.
(https://github.com/python-poetry/poetry/pull/5973, to accomodate
https://github.com/pypi/warehouse/pull/11775)

[1.1.13](https://github.com/python-poetry/poetry/releases/tag/1.1.13)
includes bugfixes that shouldn't be relevant for us (`poetry self
update` and Windows fixes only).

We shouldn't need to use 1.1.14 in the Docker image as we never `lock`
nor `update`, but I have included it for consistency.

I've also added a quick troubleshooting guide to the dev docs.
---
 .ci/scripts/test_old_deps.sh        |  2 +-
 .github/workflows/twisted_trunk.yml |  4 ++--
 docker/Dockerfile                   |  2 +-
 docs/development/dependencies.md    | 25 +++++++++++++++++++++++++
 4 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/.ci/scripts/test_old_deps.sh b/.ci/scripts/test_old_deps.sh
index 7d0625fa86f7..478c8d639ae8 100755
--- a/.ci/scripts/test_old_deps.sh
+++ b/.ci/scripts/test_old_deps.sh
@@ -69,7 +69,7 @@ with open('pyproject.toml', 'w') as f:
 "
 python3 -c "$REMOVE_DEV_DEPENDENCIES"
 
-pipx install poetry==1.1.12
+pipx install poetry==1.1.14
 ~/.local/bin/poetry lock
 
 echo "::group::Patched pyproject.toml"
diff --git a/.github/workflows/twisted_trunk.yml b/.github/workflows/twisted_trunk.yml
index f35e82297f70..dd8e6fbb1cc9 100644
--- a/.github/workflows/twisted_trunk.yml
+++ b/.github/workflows/twisted_trunk.yml
@@ -127,12 +127,12 @@ jobs:
         run: |
           set -x
           DEBIAN_FRONTEND=noninteractive sudo apt-get install -yqq python3 pipx
-          pipx install poetry==1.1.12
+          pipx install poetry==1.1.14
 
           poetry remove -n twisted
           poetry add -n --extras tls git+https://github.com/twisted/twisted.git#trunk
           poetry lock --no-update
-          # NOT IN 1.1.12 poetry lock --check
+          # NOT IN 1.1.14 poetry lock --check
         working-directory: synapse
 
       - run: |
diff --git a/docker/Dockerfile b/docker/Dockerfile
index 22707ed1425a..f4d8e6c92575 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -45,7 +45,7 @@ RUN \
 
 # We install poetry in its own build stage to avoid its dependencies conflicting with
 # synapse's dependencies.
-# We use a specific commit from poetry's master branch instead of our usual 1.1.12,
+# We use a specific commit from poetry's master branch instead of our usual 1.1.14,
 # to incorporate fixes to some bugs in `poetry export`. This commit corresponds to
 #    https://github.com/python-poetry/poetry/pull/5156 and
 #    https://github.com/python-poetry/poetry/issues/5141 ;
diff --git a/docs/development/dependencies.md b/docs/development/dependencies.md
index 8ef7d357d8cd..236856a6b047 100644
--- a/docs/development/dependencies.md
+++ b/docs/development/dependencies.md
@@ -237,3 +237,28 @@ poetry run pip install build && poetry run python -m build
 because [`build`](https://github.com/pypa/build) is a standardish tool which
 doesn't require poetry. (It's what we use in CI too). However, you could try
 `poetry build` too.
+
+
+# Troubleshooting
+
+## Check the version of poetry with `poetry --version`.
+
+At the time of writing, the 1.2 series is beta only. We have seen some examples
+where the lockfiles generated by 1.2 prereleasese aren't interpreted correctly
+by poetry 1.1.x. For now, use poetry 1.1.14, which includes a critical
+[change](https://github.com/python-poetry/poetry/pull/5973) needed to remain
+[compatible with PyPI](https://github.com/pypi/warehouse/pull/11775).
+
+It can also be useful to check the version of `poetry-core` in use. If you've
+installed `poetry` with `pipx`, try `pipx runpip poetry list | grep poetry-core`.
+
+## Clear caches: `poetry cache clear --all pypi`.
+
+Poetry caches a bunch of information about packages that isn't readily available
+from PyPI. (This is what makes poetry seem slow when doing the first
+`poetry install`.) Try `poetry cache list` and `poetry cache clear --all
+<name of cache>` to see if that fixes things.
+
+## Try `--verbose` or `--dry-run` arguments.
+
+Sometimes useful to see what poetry's internal logic is.