slohmaier/demo-epb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

feat: Project Manual + CM-/RM-Plan + Landing-Page
Validate / build-test (macos-latest) (push) Failing after 2s
Details
Validate / build-test (windows-latest) (push) Failing after 15s
Details
Validate / build-test (ubuntu-latest) (push) Failing after 15s
Details
Validate / reports (push) Has been skipped
Details
Release / release (push) Successful in 57s
Details

Browse Source 
3 neue Plaene:
- Project Manual: Master-Wegweiser fuer neue Projektmitglieder,
  Lese-Reihenfolge, Rollen, Lebenszyklus, Dokumenten-Landschaft
- Configuration Management Plan: CIs, Baselines, Change Control,
  Release-Prozess, Aufbewahrungsfristen (ASPICE SUP.8)
- Risk Management Plan: Projekt-Risiken (abgegrenzt von HARA),
  Klassifikations-Skala, Risiko-Register, Eskalations-Pfad

Landing-Page (Startseite):
- tools/generate_landing_page.py erzeugt build/index.html
- Standalone-HTML, oeffnet im Browser ohne Server
- KPI-Cards: SG/SYS/SWE/Arch/Komponenten/Tests-Counts
- Sektionen mit Links: Plaene, Safety, Manuals, Audit, Reports,
  Diagramme, Source-Code, externe Links
- Existenz-Check: nicht-generierte Reports werden grau markiert
- Im Release-Bundle als index.html ganz oben

CI-Integration:
- validate.yml: neuer Step "Landing-Page" + Upload als Artefakt
- release.yml: Landing-Page generieren + ins Bundle einbauen,
  zusaetzlich Source-Code im Bundle (war vorher nur als tar.gz)

Makefile: neues Target `make landing-page`
This commit is contained in:
Stefan Lohmaier
2026-05-12 01:59:44 -07:00
parent c610cc023c
commit 294b9956f9
10 changed files with 753 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plans-md/CM-Plan.md
+148
View File
@@ -0,0 +1,148 @@
---
doc-id: SLM-EPB-CM-001
version: 1.0
status: Freigegeben
datum: 2026-05-12
---
# Configuration Management Plan (CM-Plan)
| Feld | Wert |
|--------------|----------------------------------------|
| Projekt | demo-epb |
| Dokument-ID | SLM-EPB-CM-001 |
| Version | 1.0 |
| Status | Freigegeben |
| Datum | 2026-05-12 |
| Norm | ASPICE SUP.8 + ISO 26262-8 §7 |
---
## 1. Zweck
Beschreibt, wie Konfigurations-Items identifiziert, versioniert, freigegeben
und kontrolliert geaendert werden.
## 2. Configuration Items (CIs)
Folgende Artefakte stehen unter Konfigurationskontrolle:
| Typ | Pfad | Versionierung |
|-------------------------|----------------------------------------|------------------------------|
| Source-Code | `src/**/*.{c,h}` | Git |
| Tests | `tests/**` | Git |
| Anforderungen | `reqs/{sys,swe}/*.md` | Git + Doorstop-Item-Hash |
| Architektur | `arch/{sys,swe}/*.md` | Git + Doorstop-Item-Hash |
| Safety Goals | `safety/sg/*.md` | Git |
| Plaene (Word) | `docs/plaene/*.docx` | Git + Dokument-Versionsblock |
| Safety-Doku (Word) | `docs/safety/*.docx` | Git |
| Manuals (Word) | `docs/manuals/*.docx` | Git |
| Reviews + NCs | `docs/reviews/`, `docs/non-conformities/` | Git |
| MISRA-Records | `misra/records/*.docx` | Git |
| CI-Konfiguration | `.gitea/workflows/*.yml` | Git |
| Build-Definition | `Makefile`, `Doxyfile` | Git |
| Tools | `tools/*.py` | Git |
## 3. Repository-Struktur
- **Remote:** https://gitea.slohmaier.com/slohmaier/demo-epb
- **Branch `main`:** stabil, immer freigegebener Stand
- **Branch `develop`:** aktueller Entwicklungsstand
- **Feature-Branches:** `feature/SWE-XXX-...`
- **Bugfix-Branches:** `bugfix/<issue>-...`
- **Release-Branches:** `release/vX.Y` (nur bei Real-Projekt; Demo: direkt von main)
## 4. Baselines
Eine Baseline ist ein eingefrorener, freigegebener Stand. Baselines werden durch
Git-Tags gesetzt.
| Baseline-Typ | Tag-Schema | Wann |
|---------------------------|-------------------|----------------------------------------|
| Requirements Baseline | `req-vX.Y` | Nach Anforderungs-Freigabe |
| Architecture Baseline | `arch-vX.Y` | Nach Architektur-Review |
| Release Baseline | `vX.Y.Z` | Bei produktiver Freigabe |
| Internal Snapshot | `snap-YYYY-MM-DD` | Bei wichtigen Zwischenstaenden |
Jeder Tag triggert (bei `vX.Y.Z`) den Release-Workflow, der ein Bundle erzeugt.
## 5. Versions-Schema
| Artefakt | Schema |
|-----------------------|------------------------------------------|
| Software-Release | Semantic Versioning `MAJOR.MINOR.PATCH` |
| Anforderungen | Doorstop-Level `X.Y` + Datum |
| Architektur | Doorstop-Level `X.Y` + Datum |
| Word-Dokumente | `MAJOR.MINOR` im Dokument-Header |
## 6. Change Control
Aenderungen an Configuration Items erfolgen ueber:
1. **Trivial-Aenderung** (Tippfehler, Kommentare): direkt im Branch, PR mit 1 Approval
2. **Normal-Aenderung** (Feature, Bugfix): Feature-Branch, PR mit Reviews je nach ASIL
3. **Major-Aenderung** (Architektur, Sicherheits-Konzept): Change Request + Reviewer-Quorum
| Asil | Reviewer-Mindestanzahl |
|---------|--------------------------------------|
| QM | 1 |
| ASIL-A/B| 1 |
| ASIL-C | 2 (mind. 1 Technical Reviewer) |
| ASIL-D | 2 Technical Reviewer + Safety Manager|
Reviews werden in `docs/reviews/REV-XXX.docx` dokumentiert.
## 7. Release-Prozess
```
1. Alle PRs in main gemerged
2. Branch protected, alle CI-Checks gruen
3. Release-Notes-Entwurf im PR vorbereitet
4. Tag setzen: git tag -a vX.Y.Z -m "..."
5. Push: git push origin vX.Y.Z
6. Release-Workflow laeuft (.gitea/workflows/release.yml):
- Build + Tests + Coverage
- Traceability + Diagrams + API-Doc
- Word-Dokumente bundlen
- Source + Artefakt-Archive packen
- Gitea-Release anlegen
7. Release manuell pruefen (Bundle herunterladen, sichten)
8. Release als "stable" markieren
```
## 8. Aufbewahrung
| Artefakt | Aufbewahrungsdauer |
|--------------------------|----------------------------------------|
| Git-Repository | Unbegrenzt (Gitea + Backup) |
| Release-Bundles | 10 Jahre nach Produkt-EOL |
| Reviews + NCs | 10 Jahre nach Produkt-EOL |
| MISRA-Records | 10 Jahre nach Produkt-EOL |
| CI-Artefakte (kurzlebig) | 90 Tage (in Gitea-Artifacts) |
ISO 26262 fordert 10 Jahre nach End-of-Production-Life (Annahme).
## 9. Verifikation
Alle Pull Requests laufen durch:
- `doorstop`-aequivalenter Traceability-Check (`tools/traceability.py check`)
- Build + Unit-Tests
- Static Analysis + MISRA-Check
- Coverage-Messung
Erst nach Approval und CI-Gruen kann der Merge nach `main` erfolgen.
## 10. Verantwortlichkeiten
| Rolle | Aufgabe |
|------------------|--------------------------------------------------|
| Configuration Mgr| Pflege dieses CM-Plans, Repo-Hygiene, Baselines |
| Entwickler | Korrekte Branch-Strategie, sinnvolle Commit-Msg |
| Reviewer | Pruefung vor Merge, Audit-Trail |
| Project Owner | Release-Freigabe |
## 11. Aenderungshistorie
| Version | Datum | Aenderung | Autor |
|---------|-------------|---------------------|-------------|
| 1.0 | 2026-05-12 | Erstfreigabe | S. Lohmaier |
docs/plans-md/Project-Manual.md
+172
View File
@@ -0,0 +1,172 @@
---
doc-id: SLM-EPB-PM-MAN-001
version: 1.0
status: Freigegeben
datum: 2026-05-12
---
# Project Manual — demo-epb
| Feld | Wert |
|--------------|----------------------------------------|
| Projekt | demo-epb (Elektrische Parkbremse) |
| Dokument-ID | SLM-EPB-PM-MAN-001 |
| Version | 1.0 |
| Status | Freigegeben |
| Datum | 2026-05-12 |
| Zielgruppe | Neue Projektmitglieder, Auditoren |
---
## 1. Zweck
Dieses Project Manual ist der **Einstieg** ins demo-epb Projekt. Es beantwortet:
- Was wird gebaut?
- Welche Dokumente gibt es, in welcher Reihenfolge lesen?
- Wer ist verantwortlich wofuer?
- Wie laeuft der Entwicklungs- und Freigabe-Zyklus?
## 2. Was ist demo-epb?
Eine vollstaendige Demo des **slohmaier Dev Process** anhand einer
EPB-Steuergeraet-Software. Ziel ist **nicht** die produktive Software, sondern
der Nachweis ASPICE 4.0 / ISO 26262-konformer Entwicklung.
Detail: `docs/plaene/PID.docx`.
## 3. Lese-Reihenfolge fuer neue Projektmitglieder
| Tag | Dokument | Warum |
|-----|----------------------------------------|----------------------------------------|
| 1 | dieses Project Manual | Orientierung |
| 1 | `PID.docx` | Was + Warum |
| 1 | `User-Manual.docx` | Produkt-Verstaendnis |
| 2 | `HARA.docx` + `Safety-Case.docx` | Sicherheits-Konzept |
| 2 | `SWE-Plan.docx` + `QA-Plan.docx` | Engineering-Konventionen |
| 3 | `reqs/` + `arch/` (Markdown) | Anforderungen + Architektur |
| 3 | `src/apply_controller.c` | Beispiel ASIL-D Code |
| 4 | `traceability/index.html` | Vernetzung der Artefakte |
| 4 | `coverage/index.html` | Was ist getestet |
| 5 | Diese Anleitung selber pflegen | Onboarding fuer den Naechsten |
## 4. Dokumenten-Landschaft
```
demo-epb/
├── docs/plaene/ ← PID, PM-Plan, QA-Plan, SWE-Plan, Test-Plan, CM-Plan, RM-Plan
├── docs/safety/ ← HARA, Safety-Case, FMEDA, MISRA-Compliance, Verification-Report, Tool-Qualification
├── docs/manuals/ ← User-Manual, Service-Manual
├── docs/reviews/ ← Review-Protokolle
├── docs/non-conformities/ ← NC-Eintraege
├── misra/records/ ← MISRA Deviation Records
├── reqs/sys/ ← Doorstop-MD System Requirements
├── reqs/swe/ ← Doorstop-MD Software Requirements
├── arch/sys/ ← Doorstop-MD System Architecture + PlantUML
├── arch/swe/ ← Doorstop-MD Software Architecture + PlantUML
├── safety/sg/ ← Doorstop-MD Safety Goals (ASIL-Ableitung)
├── src/ ← C-Code, mit @arch + @reqs Tags im Header
├── tests/ ← Unit-Tests mit @reqs Tags
├── tools/ ← Python-Skripte (Traceability, PlantUML, Reports)
├── .gitea/workflows/ ← CI-Pipelines (validate + release)
└── docs/index.html ← Auto-generierte Startseite
```
Eine **klickbare Uebersicht** liefert `docs/index.html` (Browser oeffnen).
## 5. Rollen und Verantwortlichkeiten
| Rolle | Verantwortung | Person (Demo) |
|--------------------|-----------------------------------------------------|--------------------------|
| Project Owner | Strategische Entscheidungen, Freigabe Release | Stefan Lohmaier |
| Technical Lead | Architektur, Code-Reviews, technische Entscheidungen | Stefan Lohmaier |
| Safety Manager | HARA, Safety Case, ASIL-Konformitaet | Stefan Lohmaier (Demo) |
| QA-Beauftragter | QA-Plan-Pflege, Audit-Vorbereitung | Stefan Lohmaier (Demo) |
| Configuration Mgr | Baselines, Releases, Git-Repo-Hygiene | Stefan Lohmaier (Demo) |
| Entwickler | Implementierung gemaess Architektur + Tests | Stefan Lohmaier (Demo) |
| Reviewer | Code- und Dokument-Reviews | Externer Reviewer (TBD) |
In der Demo ist eine Person in allen Rollen; in einem Real-Projekt mit ASIL-C/D
sind diese personell zu trennen (insb. Entwickler ungleich Reviewer fuer
sicherheitskritischen Code).
## 6. Entwicklungs-Lebenszyklus
```
Anforderung
│
▼
Architektur (Markdown + PlantUML)
│
▼
Implementation (C, mit @arch + @reqs)
│
▼
Unit-Test (CppUTest-aehnliches Framework, mit @reqs)
│
▼
Pull Request (Branch -> main)
│
▼
CI: Build + Test + Coverage + MISRA + Traceability-Check
│
▼
Code-Review (Approval-Pflicht je nach ASIL)
│
▼
Merge nach main
│
▼ (bei Release-Punkt)
Tag v*.*.*
│
▼
CI Release-Workflow: Bundle + Gitea-Release
```
## 7. Freigabe-Strategie
- **Pull-Requests** brauchen mindestens 1 Approval (mehr fuer ASIL-C/D, siehe SWE-Plan)
- **Tags** im Format `vMAJOR.MINOR.PATCH` triggern den Release-Workflow
- **Release-Bundle** enthaelt Source + alle Reports + alle Word-Dokumente
- **Audit-Faehigkeit** ist jederzeit gegeben (Git-History + Doku-Lifecycle)
## 8. Wo Probleme melden
| Problem-Typ | Wo dokumentieren |
|-----------------------|-------------------------------------------------|
| Bug | Gitea Issue (Tag `bug`) |
| Anforderungs-Aenderung| Gitea Issue (Tag `requirement`) + Doorstop-Update |
| Non-Conformity | `docs/non-conformities-md/NC-XXX.md` -> Word |
| MISRA-Abweichung | `misra/records-md/MISRA-REC-XXX.md` -> Word |
| Sicherheits-Problem | Sofort an Safety Manager + NC |
## 9. Tools
Siehe `infrastructure/` im iCloud-Workspace fuer Setup-Details. Kurzform:
- **Gitea** (gitea.slohmaier.com) — Source-Control + CI + Releases
- **Doorstop-Stil** Markdown — Anforderungen + Architektur
- **PlantUML** — Diagramme (eingebettet)
- **Cppcheck** + **GCC -Werror** — Statische Analyse + MISRA
- **gcov/lcov** — Coverage
- **Doxygen** — API-Doc
- **pandoc** — Markdown -> Word/PDF
- **Python** (Stdlib) — Traceability + Report-Generatoren
## 10. Verwandte Dokumente
| Plan | Datei | Inhalt |
|----------------------|-------------------------------------|----------------------------------------|
| Project Initiation | `PID.docx` | Was + Warum |
| Projekt-Management | `PM-Plan.docx` | Arbeitspakete, Termine, Stakeholder |
| Quality Assurance | `QA-Plan.docx` | Reviews, Audits, NC-Management |
| Configuration Mgmt | `CM-Plan.docx` | Baselines, Releases, Change Control |
| Risk Management | `RM-Plan.docx` | Risiken, Mitigation, Monitoring |
| Software Development | `SWE-Plan.docx` | Sprache, Standards, Coverage-Ziele |
| Test | `Test-Plan.docx` | Test-Strategie |
## 11. Aenderungshistorie
| Version | Datum | Aenderung | Autor |
|---------|-------------|---------------------|-------------|
| 1.0 | 2026-05-12 | Erstfreigabe | S. Lohmaier |
docs/plans-md/RM-Plan.md
+111
View File
@@ -0,0 +1,111 @@
---
doc-id: SLM-EPB-RM-001
version: 1.0
status: Freigegeben
datum: 2026-05-12
---
# Risk Management Plan (RM-Plan)
| Feld | Wert |
|--------------|----------------------------------------|
| Projekt | demo-epb |
| Dokument-ID | SLM-EPB-RM-001 |
| Version | 1.0 |
| Status | Freigegeben |
| Datum | 2026-05-12 |
| Norm | ASPICE MAN.5 |
---
## 1. Zweck
Identifiziert, bewertet und behandelt **Projekt-Risiken** (organisatorisch,
technisch, Zeitplan, Resource). Abgegrenzt von **funktionalen Sicherheits-
Risiken** (Hazards), die im HARA behandelt werden.
## 2. Methodik
| Schritt | Aktion |
|--------------------|-------------------------------------------------|
| 1. Identifikation | Workshops, Lessons-Learned, Stakeholder-Input |
| 2. Klassifikation | Wahrscheinlichkeit (W) x Auswirkung (A) |
| 3. Bewertung | Risk Score = W * A (1-25) |
| 4. Behandlung | Vermeiden / Mindern / Akzeptieren / Transferieren |
| 5. Monitoring | Quartalsweise Review, Statusupdate |
### 2.1 Klassifikations-Skala
| Wahrscheinlichkeit | Bedeutung |
|--------------------|----------------------------|
| 1 | Sehr unwahrscheinlich |
| 2 | Unwahrscheinlich |
| 3 | Moeglich |
| 4 | Wahrscheinlich |
| 5 | Sehr wahrscheinlich |
| Auswirkung | Bedeutung |
|------------|--------------------------------------------|
| 1 | Vernachlaessigbar |
| 2 | Geringe Verzoegerung / Mehraufwand |
| 3 | Spuerbare Auswirkung auf Termin/Budget |
| 4 | Erhebliche Auswirkung, Projekt gefaehrdet |
| 5 | Projekt-Stop |
| Score-Bereich | Aktion |
|---------------|------------------------------------------|
| 1-4 | Akzeptieren, monitoren |
| 5-9 | Mindern (Plan) |
| 10-15 | Mindern (sofort, mit Eskalation) |
| 16-25 | Eskalation an Project Owner |
## 3. Risiko-Register
| ID | Beschreibung | W | A | Score | Behandlung | Status |
|-------|---------------------------------------------------------|---|---|-------|------------------------------------------|----------|
| R-01 | Demo wird als produktreifer Code missverstanden | 3 | 3 | 9 | Disclaimer im README + Project Manual | Mitigated |
| R-02 | MISRA-Tooling-Update bricht CI (false positives) | 2 | 3 | 6 | Tool-Versionen pinnen, Regression-Suite | Mitigated |
| R-03 | Reviewer-Verfuegbarkeit fuer ASIL-D | 3 | 4 | 12 | Self-Review dokumentiert (nur Demo) | Akzeptiert (Demo) |
| R-04 | Gitea-Server-Ausfall | 2 | 4 | 8 | Lokale Klone, regelmaessige Backups | Mitigated |
| R-05 | Apple-Cert-Ablauf ohne Vorwarnung | 3 | 3 | 9 | Renewal-Reminder + 30-Tage-Vorwarnung | Mitigated |
| R-06 | Windows-Build-VM unzuverlaessig (busybox-PATH-Konflikte)| 4 | 2 | 8 | MSYS2 dokumentiert, alt PATH vorne | Open |
| R-07 | macOS act_runner host-mode Cache-Bug | 3 | 2 | 6 | continue-on-error, dokumentiert | Open |
| R-08 | Doorstop-Tooling-Kompatibilitaet bei Update | 2 | 3 | 6 | Eigenes traceability.py, kein doorstop-Dep | Mitigated |
| R-09 | Wissensverlust bei Single-Person-Setup | 4 | 4 | 16 | Project Manual + Dokumentation pflegen | Open |
## 4. Risiko-Reviews
| Frequenz | Teilnehmer | Outputs |
|--------------|-------------------------|--------------------------------------|
| Quartalsweise| Project Owner + TL | Aktualisiertes Register, Action-Items |
| Bei Aenderung| Betroffene Rollen | Risiko-Score-Update |
| Bei Release | Project Owner + QA | Restrisiken-Bewertung |
## 5. Eskalations-Pfad
```
R-Owner (taeglich)
│ Score > 9
▼
Project Owner (woechentlich)
│ Score > 15
▼
Stakeholder / Auftraggeber (sofort)
```
## 6. Lessons Learned
Geschlossene Risiken werden bei Projektabschluss in `docs/lessons-learned/`
zusammengefasst, um in Folge-Projekten besser einschaetzen zu koennen.
## 7. Verwandte Dokumente
- `PM-Plan.docx` — Top-Level-Risiken (Auszug)
- `HARA.docx` — Funktionale Sicherheits-Risiken (Hazards, getrennt von Projekt-Risiken)
- `QA-Plan.docx` — Non-Conformity-Management
## 8. Aenderungshistorie
| Version | Datum | Aenderung | Autor |
|---------|-------------|---------------------|-------------|
| 1.0 | 2026-05-12 | Erstfreigabe | S. Lohmaier |