Improve documentation of schema.rs patch workflow. (#1232)

<!--
Check relevant points but **please do not remove entries**.
-->

Improved the documentation of schema.rs patch workflow

## Basics
Relevant issue #1193 
Separated out of #1191 

<!--
These points need to be fulfilled for every PR.
-->

- [X] The PR is rebased with current master
- [X] I added a line to [changelog.md](/doc/changelog.md)
- [X] Details of what I changed are in the commit messages
- [X] References to issues, e.g. `close #X`, are in the commit messages
and changelog
- [ ] The buildserver is happy

<!--
If you have any troubles fulfilling these criteria, please write about
the trouble as comment in the PR.
We will help you, but we cannot accept PRs that do not fulfill the
basics.
-->

## Checklist

<!--
For documentation fixes, spell checking, and similar none of these
points below need to be checked.
Otherwise please check these points when getting a PR done:
-->

- [X] I fully described what my PR does in the documentation
- [ ] I fixed all affected documentation
- [ ] I fixed the introduction tour
- [ ] I wrote migrations in a way that they are compatible with already
present data
- [ ] I fixed all affected decisions
- [ ] I added automated tests or a [manual test
protocol](../doc/tests/manual/protocol.md)
- [ ] I added code comments, logging, and assertions as appropriate
- [ ] I translated all strings visible to the user
- [ ] I mentioned [every code or
binary](https://github.com/ElektraInitiative/PermaplanT/blob/master/.reuse/dep5)
not directly written or done by me in [reuse
syntax](https://reuse.software/)
- [ ] I created left-over issues for things that are still to be done
- [ ] Code is conforming to [our Architecture](/doc/architecture)
- [ ] Code is conforming to [our Guidelines](/doc/guidelines)
- [ ] Code is consistent to [our Design Decisions](/doc/decisions)
- [ ] Exceptions to any guidelines are documented

## First Time Checklist

<!--
These points are only relevant when creating a PR the first time.
-->

- [ ] I have installed and I am using [pre-commit
hooks](../doc/contrib/README.md#Hooks)
- [ ] I am using [Tailwind CSS
Linting](https://tailwindcss.com/blog/introducing-linting-for-tailwindcss-intellisense)

## Review

<!--
Reviewers can copy&check the following to their review.
Also the checklist above can be used.
But also the PR creator should check these points when getting a PR
done:
-->

- [ ] I've tested the code
- [ ] I've read through the whole code
- [ ] I've read through the whole documentation
- [ ] I've checked conformity to guidelines
- [ ] I've checked conformity to requirements
- [ ] I've checked that the requirements are tested

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

@@ -65,7 +65,7 @@ Syntax: `- short text describing the change _(Your Name)_`
 - Scraper: Separate fetching of German common names from merging datasets _(Christoph Schreiner)_
 - Scraper: Allow applying overrides to merged dataset _(Christoph Schreiner)_
 - 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)_
 - _()_