From 8ba29f67f8ef7a3c5a80d0091878d441a1a6c25d Mon Sep 17 00:00:00 2001
From: Eric Eastwood <erice@element.io>
Date: Mon, 12 Sep 2022 16:24:15 -0500
Subject: [PATCH 1/4] Document common fix of Poetry problems by removing
 egg-info

---
 docs/development/dependencies.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/docs/development/dependencies.md b/docs/development/dependencies.md
index b356870f2795..94a7807f84cd 100644
--- a/docs/development/dependencies.md
+++ b/docs/development/dependencies.md
@@ -126,6 +126,23 @@ context of poetry's venv, without having to run `poetry shell` beforehand.
 poetry install --extras all --remove-untracked
 ```
 
+## ...delete everything and start over from scratch?
+
+```shell
+# Stop the current virtualenv if active
+$ deactivate
+
+# Find the venv for poetry
+$ poetry env info --path
+# Remove all the files of the current environment
+$ rm -rf $(poetry env info --path)
+
+# Reactivate Poetry shell
+$ poetry shell
+# Install everything
+$ poetry install --extras all
+```
+
 ## ...run a command in the `poetry` virtualenv?
 
 Use `poetry run cmd args` when you need the python virtualenv context.
@@ -256,6 +273,16 @@ 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.
 
+## Remove outdated egg-info
+
+Delete the `matrix_synapse.egg-info/` directory from the root of your Synapse
+install.
+
+This stores some cached information about dependencies and often conflicts with
+letting Poetry do the right thing.
+
+
+
 ## Try `--verbose` or `--dry-run` arguments.
 
 Sometimes useful to see what poetry's internal logic is.

From 1a283ac1295b5de4ae284bfce036d507d5df7769 Mon Sep 17 00:00:00 2001
From: Eric Eastwood <erice@element.io>
Date: Mon, 12 Sep 2022 16:28:05 -0500
Subject: [PATCH 2/4] Add changelog

---
 changelog.d/13785.doc | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 changelog.d/13785.doc

diff --git a/changelog.d/13785.doc b/changelog.d/13785.doc
new file mode 100644
index 000000000000..6d4eb7eb996a
--- /dev/null
+++ b/changelog.d/13785.doc
@@ -0,0 +1 @@
+Add docs for common fix of deleting the `matrix_synapse.egg-info/` directory for fixing Python dependency problems.

From 6aa8d7b012a2f0ae150a517cf771735df61307cc Mon Sep 17 00:00:00 2001
From: Eric Eastwood <erice@element.io>
Date: Mon, 12 Sep 2022 16:28:58 -0500
Subject: [PATCH 3/4] Better wording

---
 docs/development/dependencies.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/development/dependencies.md b/docs/development/dependencies.md
index 94a7807f84cd..855fe66281ae 100644
--- a/docs/development/dependencies.md
+++ b/docs/development/dependencies.md
@@ -134,7 +134,7 @@ $ deactivate
 
 # Find the venv for poetry
 $ poetry env info --path
-# Remove all the files of the current environment
+# Remove all of the files from the current environment
 $ rm -rf $(poetry env info --path)
 
 # Reactivate Poetry shell

From 72d0309dc866ba39d02029960a2039c5f08619e2 Mon Sep 17 00:00:00 2001
From: Eric Eastwood <erice@element.io>
Date: Thu, 15 Sep 2022 14:35:46 -0500
Subject: [PATCH 4/4] Alternative to removing the venv

See https://github.com/matrix-org/synapse/pull/13785#discussion_r970784383
---
 docs/development/dependencies.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/development/dependencies.md b/docs/development/dependencies.md
index 855fe66281ae..8474525480d6 100644
--- a/docs/development/dependencies.md
+++ b/docs/development/dependencies.md
@@ -132,14 +132,14 @@ poetry install --extras all --remove-untracked
 # Stop the current virtualenv if active
 $ deactivate
 
-# Find the venv for poetry
-$ poetry env info --path
-# Remove all of the files from the current environment
-$ rm -rf $(poetry env info --path)
+# Remove all of the files from the current environment.
+# Don't worry, even though it says "all", this will only
+# remove the Poetry virtualenvs for the current project.
+$ poetry env remove --all
 
-# Reactivate Poetry shell
+# Reactivate Poetry shell to create the virtualenv again
 $ poetry shell
-# Install everything
+# Install everything again
 $ poetry install --extras all
 ```