Improve documentation of schema.rs patch workflow.

doc/backend/06updating_schema_patch.md

@@ -1,8 +1,24 @@
-# Update the `schema.patch` file
+## Why do we need the `schema.patch` file
 
-This document explains how to update the `schema.patch` file used by diesel.
+When executing `diesel migration run` diesel connects to the database and expresses the current schema of the database in the `schema.rs` file. The config for this mechanism is in `diesel.toml`. You can use `diesel print-schema` to output the schema manually. Unfortunately Diesel generates type definitions for types we import from Postgis.
+This results in a double use:
 
-1. Remove the following line from `diesel.toml`:
+```
+diesel::table! {
+    use postgis_diesel::sql_types::Geography; // <-- even though we import using --import-types
+    use super::sql_types::Geography;          // <-- this gets generated by Diesel
+```
+
+After generating the `schema.rs` file Diesel applies the patch file to it.
+
+## When to update the `schema.patch` file
+
+Whenever you get an error message similar to `error applying hunk #2` you have to update the `schema.patch` file.
+This happens when `schema.rs` changes in the diff context of the patch file (the lines before and after the change).
+
+## How to update the `schema.patch` file
+
+1. Comment out the following line from `diesel.toml`:
 
    ```toml
    patch_file = "src/schema.patch"
@@ -17,7 +33,13 @@ This document explains how to update the `schema.patch` file used by diesel.
    You should now have a generated `schema.rs` in the backend src folder.
 
 3. Copy the `schema.rs` file e.g. to `schema_tmp.rs`.
-4. Run `` diff src/schema.rs `src/schema_tmp.rs` -U6 `` in the backend folder and save the result to the `src/schema.patch` file.
-5. Add `patch_file = "src/schema.patch"` to the `diesel.toml` again.
 
-From now on the newly generated patch file should be used by diesel.
+4. Make the necessary changes to `schema_tmp.rs`.
+
+5. In the backend directory run `diff -U6 src/schema.rs src/schema_tmp.rs > src/schema.patch`.
+
+6. Add `patch_file = "src/schema.patch"` to the `diesel.toml` again.
+
+7. Delete `schema_tmp.rs`.
+
+From now on the newly generated patch file should be used by Diesel.

doc/changelog.md

@@ -59,7 +59,7 @@ Syntax: `- short text describing the change _(Your Name)_`
 - _()_
 - _()_
 - Make map geometry viewable and editable _(Moritz)_
-- _()_
+- Improve documentation of schema.rs patch workflow. _(Jannis @horenso, Christoph @chr_schr)_
 - Prevent propagating enft key on markdown editor _(Daniel Steinkogler)_
 - Enable deletion of selected plants via DEL shortcut _(Daniel Steinkogler)_
 - _()_