diff --git a/guidelines.md b/guidelines.md new file mode 100644 index 0000000..54d0546 --- /dev/null +++ b/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//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__`, wobei `` 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", …}, …]}`