Entwicklung
Dieser Bereich richtet sich an alle, die am Projekt selbst weiterarbeiten – sei es am Skript (source/main.sh) oder an der Dokumentation. Er fasst die im Projekt gelebten Konventionen kurz zusammen.
Repository-Struktur
| Pfad | Inhalt |
|---|---|
source/ | Das eigentliche Produkt: main.sh und userdata.yml.template |
docs/ | Jekyll-Dokumentation (Just-the-Docs) |
docs/_includes/ | Zentrale Inhalte als Includes (Single Source of Truth) |
.admin/ | Vorgaben, Standards (Standards_AbyssInc.md) und Merkblätter |
.gitlab/ | Issue-Templates für User Stories und Tasks |
README.md / userdocumentation.md | Stand-Alone-Dokumente, die dieselben Includes einbinden |
Doku-as-Code
Die gesamte Dokumentation folgt dem Prinzip “Single Source of Truth”: Inhalte werden einmal unter docs/_includes/ gepflegt und sowohl von den Jekyll-Seiten ({% include ... %}) als auch von den Repository-Dokumenten (::include{file=...}) referenziert. Inhalte werden daher nie doppelt gepflegt – immer den Include bearbeiten, nicht die Wrapper-Seite.
Coding-Standards (main.sh)
- Strict Mode: Jedes Skript startet mit
set -euo pipefail. - Funktionaler Monolith: Neue Fähigkeiten werden als eigene, klar benannte Funktion ergänzt (siehe Architekturentscheid), nicht als Inline-Code im
main()-Fluss. - Sprechende Namen: Funktions- und Variablennamen beschreiben ihren Zweck (
select_environment,load_environment_defaults). - Fixe Werte zentral halten: Standardwerte stammen aus
/.admin/Standards_AbyssInc.md, nicht verstreut im Code. - Nicht-interaktive Umgebungen mitdenken: Ausgaben, die eine echte Konsole voraussetzen (z. B. Spinner), über
[[ -t 1 ]]absichern.
Git-Workflow
- Gearbeitet wird auf
main; Commits erfolgen laufend und dienen gleichzeitig der Versionierung als Backup (siehe Risikomanagement). - Aussagekräftige Commit-Messages bevorzugen.
- Issues werden über die Templates in
.gitlab/issue_templates/als User Story oder Task erfasst und über das Issue Board (Kanban) geführt.
Lokale Vorschau der Dokumentation
bundle install
bundle exec jekyll serve --source docs
Die öffentlich gebaute Version wird über die GitLab-CI-Pipeline (.gitlab-ci.yml) nach docs.abyss.li deployed.