document releases/next file

See coop-cloud/abra#391.

Dockerfile

@@ -1,4 +1,4 @@
-FROM squidfunk/mkdocs-material:9.4.11
+FROM squidfunk/mkdocs-material:9.4.14
 
 EXPOSE 8000
 

docs/abra/hack.md

@@ -62,14 +62,16 @@ cd bats-core
 sudo ./install.sh /usr/local
 ```
 
-### Run tests
+### Setup Test Server
 
-Then you can run the integration test suite with the following.
+For many tests an actual server is needed, where apps can be deployed. You can
+either use a local one or a remote test server.
+
+#### With remote test server
 
 ```
 export ABRA_TEST_DOMAIN="test.example.com"
 export ABRA_DIR="$HOME/.abra_test"
-bats -Tp tests/integration # DO NOT run this just yet, read below...
 ```
 
 `ABRA_TEST_DOMAIN` should also have a DNS A record for `*.test.example.com`
@@ -81,6 +83,32 @@ Traefik for you. Then you'll have more stable results.
 You probably don't want to run the entire test suite though, it takes a while.
 Try the following for starters.
 
+#### With local swarm
+
+When running the test suite localy you need a running docker swarm setup:
+
+```
+docker swarm init
+docker network create -d overlay proxy
+```
+
+To use the local swarm set the foloowing env var:
+
+```
+export TEST_SERVER=default
+export ABRA_DIR="$HOME/.abra_test"
+```
+
+### Run tests
+
+Now you can run the whole test suite:
+
+```
+bats -Tp tests/integration
+```
+
+Or you can run a single test file:
+
 ```
 bats -Tp tests/integration/autocomplete.bats
 ```
@@ -225,7 +253,7 @@ For developers, while using this `-beta` format, the `y` part is the "major" ver
 
 ### `godotenv`
 
-We maintain a fork of [godotenv](https://github.com/Autonomic-Cooperative/godotenv) because we need inline comment parsing for environment files. You can upgrade the version here by running `go get github.com/Autonomic-Cooperative/godotenv@<commit>` where `<commit>` is the latest commit you want to pin to. At time of writing, `go get github.com/Autonomic-Cooperative/godotenv@b031ea1211e7fd297af4c7747ffb562ebe00cd33` is the command you want to run to maintain the above functionality.
+We maintain a fork of [godotenv](https://git.coopcloud.tech/coop-cloud/godotenv) because we need inline comment parsing for environment files. You can upgrade the version here by running `go get git.coopcloud.tech/coop-cloud/godotenv@0<COMMID>` where `<commit>` is the latest commit you want to pin to. See [`abra#391`](https://git.coopcloud.tech/coop-cloud/abra/pulls/391) for more.
 
 ### `docker/client`
 

docs/federation/resolutions/in-progress/013.md

@@ -0,0 +1,83 @@
+---
+title: "Resolution 013: Budget 007: Operator sync - 2023-10-14"
+---
+
+- Deadline: 2023-10-28
+- Size: Large
+
+### Summary
+
+As highlighted in several tickets (e.g. [`#434`](https://git.coopcloud.tech/coop-cloud/organising/issues/434), [`#467`](https://git.coopcloud.tech/coop-cloud/organising/issues/467)), several operators working together on the same server routinely run into deployment instability. This is due to the fact that we do not store or sync the deployment version of the apps.
+
+With this proposal, we would like to address the synchronisation of app deployment versions. This is being called "Operator sync". What follows is the design proposal which has already received feedback from operators on [this pad](https://pad.riseup.net/p/IebZQkpe3OOpYyVT8f1j-keep).
+
+### Details (Budget 007)
+
+We support a config file (`$ABRA_DIR/config.yml`) which has these defaults:
+
+```yaml
+---
+operator:
+  sync: false
+```
+
+We also add a `abra config` command which has the following shape:
+
+```
+🌻 ./abra config -h
+NAME:
+   abra config - Manage system-wide Abra configuration
+
+USAGE:
+   abra config command [command options]
+
+COMMANDS:
+   generate, g  Generate default configuration
+
+OPTIONS:
+   --help, -h  show help
+```
+
+If there is no `$ABRA_DIR/config.yml` or `sync: false`, nothing changes. When `sync: true`, *only* the `abra app deploy / upgrade / rollback` commands have new behaviour.
+
+There is also a new command `abra app sync <domain>` which triggers a synchronisation.
+
+When `abra app deploy/upgrade/rollback/sync` is run, here's what we do:
+
+* `git pull` on the sync repository
+    * if there are changes, pull them in & log them
+    * if there is a merge conflict, bail out and ask operator to resolve them
+
+`abra` will search for Git repositories under `$ABRA_DIR/servers/...`. A single Git repository at the root (`$ABRA_DIR/servers/.git`) and on the individual server level (`$ABRA_DIR/servers/example.com/.git`) are supported. Both solution work alongside each other and symlinks are resolved.
+
+The way to avoid merge conflicts will be to never move the `OPERATOR_SYNC_VERSION` env var (see below) from the line it is on in the app env config. `abra` will always insert it just under the `TYPE` env var.
+
+The initial implementation asks operators to initialise their own Git repositories.
+
+* Read the `OPERATOR_SYNC_VERSION` env var as the version to deploy / upgrade from / rollback from
+    * upgrade: if deployed version does not match `OPERATOR_SYNC_VERSION`, warn before overview
+    * rollback: same as above!
+
+* Run the deployment
+    * if successful, record a new `OPERATOR_SYNC_VERSION`, commit & push the changes
+    * if unsuccessful, do not record a `OPERATOR_SYNC_VERSION` and ask operator to resolve
+
+If `--chaos` is passed, we use the short commit hash instead of the version label.
+
+Here's an example of the `OPERATOR_SYNC_VERSION` env var:
+
+```
+# in ~/.abra/servers/example.com/matrix.example.com.env
+TYPE=matrix-synapse
+OPERATOR_SYNC_VERSION=4.0.0+v1.93.0 # managed by Abra
+```
+
+Operator documentation will also be provided.
+
+**Budget amount**: 400 EUR (20 hrs * 20 EUR/hr)
+
+**Who will implement this**: decentral1se
+
+**When will the money be spent**: Before mid November 2023.
+
+**What is the money for**: Implementing the first steps of operator sync.

docs/federation/resolutions/in-progress/014.md

@@ -0,0 +1,44 @@
+---
+title: "Resolution 014: Budget 008: Critical Fixes - 2023-12-06"
+---
+
+- Deadline: 2023-12-24
+- Size: Large
+
+
+## Summary
+
+We (decentral1se, wykwit, moritz, knoflook) have identified bugs and lacking features that are a big obstacle to using abra.
+
+We have roughly estimated the work to fix the bugs to take between 27 and 75 hours. We would also like to request onboarding budget for two new developers to smoothly get started on the bug fixes (10 hours per person).
+
+We'd like to request no more than 1900€ of budget to cover the labor and onboarding. If less than 95 hours is spent, the remaining budget will not be paid out.
+
+## Details
+
+estimating: small (1-3 hours), medium (3-8 hours), large (8-15 hours) & order is priority.
+
+
+| NAME | estimation |
+| ---- | ----- |
+| [#535 Comment parsing and modifiers](https://git.coopcloud.tech/coop-cloud/organising/issues/535) | Large |
+| [#519 abra app new [<recipe>] [<version>]](https://git.coopcloud.tech/coop-cloud/organising/issues/519) | Medium |
+| [#518 Abra fails silently if required image doesn't exist](https://git.coopcloud.tech/coop-cloud/organising/issues/518) | Medium |
+| [#527 abra catalogue generate `<recipe name>` ignores the specified recipe](https://git.coopcloud.tech/coop-cloud/organising/issues/527) | Small |
+| [#509 abra app remove could wait until volume is not in use](https://git.coopcloud.tech/coop-cloud/organising/issues/509) | Medium |
+| [#530 abra recipe fetch can only fetch a single recipe](https://git.coopcloud.tech/coop-cloud/organising/issues/530) | Medium |
+| [#525 prevent abra app cp from applying file permissions.](https://git.coopcloud.tech/coop-cloud/organising/issues/525) | Medium |
+| [#537 Fix the operators tutorial](https://git.coopcloud.tech/coop-cloud/organising/issues/537) | Medium |
+
+Estimation: best case: (8 * 1) + (3 * 6) + (1 * 1) = 27 hours
+Estimation: worst case: (15 * 1) + (8 * 6) + (1 * 3) = 73 hours
++ 10 hours for onboarding * 2 people = 47-93 hours
+
+
+**Budget amount**: 1900€/95 hours at maximum
+
+**Who will implement this:** p4u1, wykwit, decentral1se, moritz, knoflook
+
+**When will the money be spent:** Before the end of February 2024.
+
+**What is the money for:** Fixing bugs and improving operator docs.

docs/maintainers/handbook.md

@@ -396,6 +396,8 @@ mkdir -p releases
 
 And then create a text file which corresponds to the version release, e.g. `1.1.0+5.9.0` and write some notes. `abra` will show these when another operator runs `abra app deploy` / `abra app upgrade`.
 
+You can also add release notes for the next release into a special file `releases/next`. This file will be used when running `abra recipe release`.
+
 ## How do I generate the recipe catalogue
 
 To generate an entire new copy of the catalogue:

mkdocs.yml

@@ -103,6 +103,8 @@ nav:
           - federation/resolutions/passed/012.md
         - "In progress":
           - federation/resolutions/in-progress/index.md
+          - federation/resolutions/in-progress/013.md
+          - federation/resolutions/in-progress/014.md
         - "Draft":
           - federation/resolutions/drafts/index.md
       - "Finance": federation/finance.md

requirements.txt

@@ -1,4 +1,4 @@
 mkdocs-awesome-pages-plugin==2.9.2
 mkdocs-material-extensions==1.3.1
-mkdocs-material==9.4.11
+mkdocs-material==9.4.14
 mkdocs==1.5.3