hacking: add some explanatory notes

Signed-off-by: Vlad-Stefan Harbuz <vlad@vladh.net>

2 files changed, 29 insertions, 4 deletions

diff --git a/git.sr.ht/configuration.md b/git.sr.ht/configuration.md
index e11b69c..d8c45f6 100644
--- a/git.sr.ht/configuration.md
+++ b/git.sr.ht/configuration.md
@@ -65,6 +65,10 @@ for additional services (e.g. man.sr.ht).
 Authorization logs are written to `/var/log/gitsrht-dispatch` and
 `gitsrht-shell`.
 
+If you have any issues with dispatch, please make sure the `git` user is not
+locked by setting a password for it, and also make sure you can otherwise SSH
+into it.
+
 # HTTP(S) Cloning
 
 git.sr.ht does not handle HTTP(S) cloning for you, so you'll need to set it up
diff --git a/hacking.md b/hacking.md
index 06759c9..b1e46f1 100644
--- a/hacking.md
+++ b/hacking.md
@@ -37,10 +37,19 @@ packages from source requires additional build-time dependencies:
 
 Do this once, when starting with meta.sr.ht:
 
-* In addition to meta.sr.ht, check out
-  [core.sr.ht](https://git.sr.ht/~sircmpwn/core.sr.ht)
+* Check out [meta.sr.ht](https://git.sr.ht/~sircmpwn/meta.sr.ht) and
+  [core.sr.ht](https://git.sr.ht/~sircmpwn/core.sr.ht). Make sure to clone with
+  `--recurse-submodules`.
 * Copy meta.sr.ht's `config.example.ini` to `config.ini` and configure
   everything following the instructions in the comments.
+* Run `npm install` in the `core.sr.ht/srht` directory.
+
+When filling in the `config.ini` file, remember the following:
+
+* Some of the comments will ask you to run programs such as `srht-keygen` —
+  these can be found in the core.sr.ht repository.
+* If you do not have SSL enabled for Postgres, be sure to add `?sslmode=disable`
+  to the end of your Postgres URL.
 
 Then, for each `SERVICE`:
 
@@ -48,6 +57,11 @@ Then, for each `SERVICE`:
 * `export PYTHONPATH=/path/to/core.sr.ht:/path/to/$SERVICE`
 * `make all`
 
+To avoid conflicts with the `email` package, you should now `unset PYTHONPATH`.
+
+Note that core.sr.ht is not a service, but merely a repository of code shared
+between services.
+
 For each service *except* meta.sr.ht:
 
 * Copy the service's section(s) from its `config.example.ini` into meta.sr.ht's
@@ -61,8 +75,15 @@ For each `SERVICE`:
 
 To run a service:
 
-* `./api/api`
-* `python run.py`
+* `./api/api` (must be run before the following command)
+* `python3 run.py`
+
+For the APIs to be able to talk to each other, you need to correctly register
+each service as a client. You will find more instructions on the
+meta.example.org/oauth page, as well as in the [OAuth
+Reference](https://man.sr.ht/meta.sr.ht/oauth-api.md). After you have created
+the OAuth clients, find each respective database entry in the `oauthclient`
+table, and set the `preauthorized` column to `TRUE` for each one.
 
 # Sending Patches