[add] guidelines

guidelines.md

@@ -0,0 +1,33 @@
+# Richtlinien
+
+## Allgemeines
+
+- alle Definitionen sollen in JSON erfolgen (statt YAML und TOML)
+- Rollen sollen grundsätzlich so gestaltet sein, dass sie wiederverwendbar sind, also nicht auf eine bestimmte Lage zugeschnitten
+
+
+## Rollen
+
+- sollen jeweils eine Info-Datei enthalten (`roles/<rollen-name>/info.md`), in welcher kurz der Zweck der Rolle beschrieben, mögliche Besonderheiten für die Verwendung erklärt und nützliche Angaben wie Netz-Verweise aufgeführt werden
+
+
+### Namen
+
+- gewöhnliche Rollen sollen nur mit Kleinbuchstaben und Unterstrichen benannt sein
+- Abhängigkeiten sollen durch den Infix `-for-` gekennzeichnet werden, wobei links die Quelle und rechts die Senke steht
+- Konvergenzen (keines hängt vom jeweils anderen stark ab) sollen durch den Infix `-with-` gekennzeichnet werden, wobei die Reihenfolge der beteiligten Unterrollen an sich egal ist, jedoch einheitlich sein sollte, d.h. wenn es bereits `a-with-b` gibt, sollte nicht `c-with-a` angelegt werden, sondern `a-with-c`
+
+
+### Variablen
+
+- sollen nach folgendem Muster benannt sein: `var_<rollen-name>_<bezeichnung>`, wobei `<bezeichnung>` aussagekräftig sein soll (z.B. `server_port` statt `x1`)
+- sollen mit sinnvollen Standard-Werten belegt werden
+- sollen aufgelistet/angekündigt/deklariert 
+- sollen möglichst primitiv sein, d.h. nur Wahrheits-Werte, Zahlen und (einfache) Zeichenketten
+
+
+## Playbooks
+
+- sollen keine eigenen Tasks enthalten: (`{"tasks": []}`)
+- sollen keine freien Variablen enthalten (`{"vars": {}}`)
+- sollen Rollen in folgendener Struktur angeben: `{"roles": [{"role": "foo", "var_foo_1": "a", "var_foo_2": "b", …}, {"role": "bar", "var_bar_1": "c", "var_bar_2": "d", …}, …]}`