Entwicklung
Dieser Bereich richtet sich an alle, die am Projekt selbst weiterarbeiten, sei es an der Infrastruktur, der Lambda oder an der Dokumentation. Er fasst die im Projekt gelebten Konventionen kurz zusammen.
Repository-Struktur
| Pfad | Inhalt |
|---|---|
source/ | Das eigentliche Produkt: Terraform, Lambda (Python) und Demo-Anwendung |
docs/ | Jekyll-Dokumentation (Just-the-Docs) |
docs/_includes/ | Zentrale Inhalte als Includes (Single Source of Truth) |
.admin/ | Einreichungsformular und Merkblatt |
.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.
Infrastruktur-Regeln
- Nur Terraform: Die Basis-Infrastruktur wird ausschliesslich über Terraform und die Pipeline verändert, keine manuellen Änderungen in der AWS-Konsole.
- Review-Instanzen nur aus dem Launch Template: Die Lambda startet Instanzen ausschliesslich aus dem versionierten Launch Template.
- Remote State in S3, einheitliches Tagging (Projekt, MR-ID).
- Keine Secrets im Repository: geschützte CI/CD-Variablen, GitLab-Token im SSM Parameter Store.
Git-Workflow
- Gearbeitet wird über Merge Requests, da jeder MR gleichzeitig seine eigene Review-Umgebung testet.
- 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.sa2.ronova.to deployed.