From 8b337a5a2449584e2a3a01d61911f535f083e1e1 Mon Sep 17 00:00:00 2001
From: Grant McLean <grant@catalyst.net.nz>
Date: Thu, 25 May 2023 17:19:01 +1200
Subject: [PATCH] Documentation improvements to contributing guide (#15667)

- Reiterate the importance of getting Rust installed and set up before
  attempting to install the Python dependencies.

- Mention the importance of confirming that `poetry install` completed
  successfully and include a typical error that the user might see if it
  did not.

- Expand on "Now edit homeserver.yaml" to give examples of things likely
  to need changing and to link to the relevant sections of the Synapse
  server documentation.

Signed-off-by: Grant McLean <grant@catalyst.net.nz>
---
 docs/development/contributing_guide.md | 32 ++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/docs/development/contributing_guide.md b/docs/development/contributing_guide.md
index 56cf4ba81e54..eb565672e8d4 100644
--- a/docs/development/contributing_guide.md
+++ b/docs/development/contributing_guide.md
@@ -53,6 +53,13 @@ can find many good git tutorials on the web.
 
 # 4. Install the dependencies
 
+Before installing the Python dependencies, make sure you have installed Rust (see the
+"What do I need?" section above) and have selected the default Rust toolchain:
+
+```sh
+rustup default stable
+```
+
 Synapse 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`.
@@ -76,7 +83,8 @@ cd path/where/you/have/cloned/the/repository
 poetry install --extras all
 ```
 
-This will install the runtime and developer dependencies for the project.
+This will install the runtime and developer dependencies for the project.  Be sure to check
+that the `poetry install` step completed cleanly.
 
 ## Running Synapse via poetry
 
@@ -84,14 +92,34 @@ To start a local instance of Synapse in the locked poetry environment, create a
 
 ```sh
 cp docs/sample_config.yaml homeserver.yaml
+cp docs/sample_log_config.yaml log_config.yaml
 ```
 
-Now edit homeserver.yaml, and run Synapse with:
+Now edit `homeserver.yaml`, things you might want to change include:
+- setting a servername
+- fixing pathnames to be correct for your system
+- using a PostgreSQL database instead of SQLite
+- adding a [registration_shared_secret](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#registration_shared_secret)
+  for use with [register_new_matrix_user](https://matrix-org.github.io/synapse/latest/setup/installation.html#registering-a-user)
+
+edit `log_config.yaml` if necessary:
+- you may wish to set the root handler for logging in your dev environment to `console`
+
+and run Synapse with:
 
 ```sh
 poetry run python -m synapse.app.homeserver -c homeserver.yaml
 ```
 
+If you get an error like the following:
+
+```
+importlib.metadata.PackageNotFoundError: matrix-synapse
+```
+
+this probably indicates that the `poetry install` step did not complete cleanly - go back and
+resolve any issues and re-run until successful.
+
 # 5. Get in touch.
 
 Join our developer community on Matrix: [#synapse-dev:matrix.org](https://matrix.to/#/#synapse-dev:matrix.org)!