docs: moar info on perms, formatting

docs/abra/hack.md

@@ -8,6 +8,17 @@ Welcome to Hacking the Planet with `abra`! We're looking forward to see what you
 
 In general, we're into the idea of "Optimistic Merging" (instead of "Pessimistic Merging" based on our understanding of [C4](https://hintjens.gitbooks.io/social-architecture/content/chapter4.html) (described further down under "Development Process" and also [in this blog post](http://hintjens.com/blog:106)).
 
+In other words, we're happy to give you, as contributor, "the commit bit" (read/write permissions on the Git repositories) more or less as soon as you start to submit changes, write recipes, organise or in general, help out in the project. You don't have to prove anything, we can work and learn together! Mistakes are allowed and there are no "stupid questions".
+
+We maintain a "team" called "Co-operators" on our 2 main repositories:
+
+* [Toolshed](https://git.coopcloud.tech/org/toolshed/)
+* [the recipes](https://git.coopcloud.tech/org/coop-cloud/)
+
+This gives you read/write access to all the repositories of the organisation.
+
+Any existing contributor can add you.
+
 ## Quick start
 
 Get a fresh copy of the `abra` source code from [here](https://git.coopcloud.tech/toolshed/abra).
@@ -21,7 +32,7 @@ Install [Go >= 1.16](https://golang.org/doc/install) and then:
 - `make test` will run tests
 - `make install-abra` will install abra to `$GOPATH/bin`
 - `make install-kadabra` will install kadabra to `$GOPATH/bin`
-- `go get <package>` and `go mod tidy` to add a new dependency
+- `go get <package>`, `go mod tidy` and `go mod vendor` to add a new dependency
 
 Our [Drone CI configuration](https://git.coopcloud.tech/toolshed/abra/src/branch/main/.drone.yml) runs a number of checks on each pushed commit. See the [Makefile](https://git.coopcloud.tech/toolshed/abra/src/branch/main/Makefile) for more handy targets.
 
@@ -49,17 +60,13 @@ go test ./pkg/recipe -v -run TestGetVersionLabelLocalDoesNotUseTimeoutLabel
 
 ### Running on the CI server
 
-Based on
+Based on [R020](https://docs.coopcloud.tech/federation/resolutions/passed/020/), we have automated running the integration test suite. Here's the TLDR;
-[R020](https://docs.coopcloud.tech/federation/resolutions/passed/020/), we have
-automated running the integration test suite. Here's the TLDR;
 
-* We have a donated CI server (tysm `@mirsal` 💝) standing at the ready,
+* We have a donated CI server (tysm `@mirsal` 💝) standing at the ready, `int.coopcloud.tech`.
-  `int.coopcloud.tech`.
 * We run the entire integration suite nightly via our Drone CI/CD configuration [here](https://git.coopcloud.tech/toolshed/abra/src/branch/main/.drone.yml) (see "`name: integration test`" stanza)
 * Here is the script that is run on the remote server: [`run-ci-int`](https://git.coopcloud.tech/toolshed/abra/src/branch/main/scripts/tests/run-ci-int)
 
-What follows is a listing of how this was achieved so that we can collectivise
+What follows is a listing of how this was achieved so that we can collectivise the maintenance.
-the maintenance.
 
 On the server, we have:
 
@@ -82,17 +89,13 @@ Please ask `@decentral1se` or on the Matrix channels for SSH access to the machi
 
 #### Install dependencies
 
-We use [`bats`](https://bats-core.readthedocs.io/en/stable/) to run the tests.
+We use [`bats`](https://bats-core.readthedocs.io/en/stable/) to run the tests. You can install the required dependencies with the following. You also need a working installation of Docker and Go >= 1.16 (not covered in this section).
-You can install the required dependencies with the following. You also need a
-working installation of Docker and Go >= 1.16 (not covered in this section).
 
 ```
 apt install bats-file bats-assert bats-support jq make git
 ```
 
-Unfortunately, the latest `bats` version in Debian stable does not have the
+Unfortunately, the latest `bats` version in Debian stable does not have the "filter tests by tags" feature, which is very handy for running a subset of the tests. For this, we need to install `bats` from source. It's easy.
-"filter tests by tags" feature, which is very handy for running a subset of the
-tests. For this, we need to install `bats` from source. It's easy.
 
 ```
 apt purge -y bats
@@ -103,10 +106,7 @@ sudo ./install.sh /usr/local
 
 #### Setup Test Server
 
-For some tests an actual server is needed, where apps can be deployed. You can
+For some tests an actual server is needed, where apps can be deployed. You can either use a local one or a remote test server. There is also a way to run or skip tests that require a remote server. This is covered below in the [filtering tests](#filter-tests_1) section.
-either use a local one or a remote test server. There is also a way to run or
-skip tests that require a remote server. This is covered below in the
-[filtering tests](#filter-tests_1) section.
 
 ##### Remote swarm
 
@@ -115,9 +115,7 @@ export ABRA_TEST_DOMAIN="test.example.com"
 export ABRA_DIR="$HOME/.abra_test"
 ```
 
-`ABRA_TEST_DOMAIN` should also have a DNS A record for `*.test.example.com`
+`ABRA_TEST_DOMAIN` should also have a DNS A record for `*.test.example.com` which points to the same server so that the test suite can deploy apps freely. The test suite does not deploy Traefik for you.
-which points to the same server so that the test suite can deploy apps freely.
-The test suite does not deploy Traefik for you.
 
 ##### Local swarm
 
@@ -146,13 +144,12 @@ bats -Tp tests/integration
 Or you can run a single test file:
 
 ```
-bats -Tp tests/integration/autocomplete.bats
+bats -Tp tests/integration/app_check.bats
 ```
 
 ### Tagging tests
 
-When a test actually deploys something, we tag it as "slow". When the test
+When a test actually deploys something, we tag it as "slow". When the test requires public DNS, we use "dns". There may be more tags we write more tests.
-requires public DNS, we use "dns". There may be more tags we write more tests.
 
 ```
 # bats test_tags=slow,dns
@@ -161,18 +158,14 @@ requires public DNS, we use "dns". There may be more tags we write more tests.
 }
 ```
 
-Then we can use [filters](#filter-tests) (see below) to pick out a subset of
+Then we can use [filters](#filter-tests) (see below) to pick out a subset of tests which do/do not use a live server. Feel free to come up with your own tags. See the `bats-core` [docs](https://bats-core.readthedocs.io/en/stable/writing-tests.html#tagging-tests) for more.
-tests which do/do not use a live server. Feel free to come up with your own
-tags. See the `bats-core`
-[docs](https://bats-core.readthedocs.io/en/stable/writing-tests.html#tagging-tests)
-for more.
 
 ### Filter tests
 
 You can run a specific file.
 
 ```
-bats -Tp tests/integration/autocomplete.bats
+bats -Tp tests/integration/app_check.bats
 ```
 
 For example, if you want to check that all `abra recipe ...` tests remain working.
@@ -205,9 +198,7 @@ bats -Tp tests/integration --filter-status failed # re-run only failed
 
 ### Debug tests
 
-If you're running into issues and want to debug stuff, you can pass `-x` to
+If you're running into issues and want to debug stuff, you can pass `-x` to `bats` to trace all commands run in the test. You can add `echo '...' >&3` debug statements to your test to output stuff also.
-`bats` to trace all commands run in the test. You can add `echo '...' >&3`
-debug statements to your test to output stuff also.
 
 ## Using the `abra` public API