feat(i18n): full English translation of demo-epb
Validate / build-test (macos-latest) (push) Failing after 3s
Validate / build-test (windows-latest) (push) Failing after 15s
Validate / build-test (ubuntu-latest) (push) Successful in 17s
Validate / reports (push) Successful in 50s
Release / release (push) Successful in 50s

Phase 2 of the English translation:

Word documents (filled, EPB-specific):
- 8 plans (PID, PM, QA, SWE, Test, Project Manual, CM, RM)
- 6 safety docs (HARA, Safety Case, FMEDA, MISRA Compliance,
  Verification Report, Tool Qualification Cppcheck)
- 2 manuals (User, Service)
- 3 audit artefacts (Review minutes, NC-001, MISRA-REC-001)
- All regenerated via pandoc from English markdown sources

Code, tests, headers:
- All file headers, struct comments, function docstrings in English
- All test names (TEST_BEGIN strings) translated
- Inline comments translated
- 46 tests still green after translation

CI workflows:
- All step names in English
- Step descriptions, comments, release notes template in English

README.md fully rewritten in English with proper guided tour.

Phase 3 (still pending): dev-process repo templates + toolstack/setup docs.
This commit is contained in:
Stefan Lohmaier
2026-05-12 03:37:51 -07:00
parent a47e0aed3e
commit fb2c083551
54 changed files with 1528 additions and 1600 deletions
+95 -94
View File
@@ -1,139 +1,141 @@
# demo-epb — Elektrische Parkbremse
# demo-epb — Electric Parking Brake
Vollständige Demo des [slohmaier Dev Process](https://gitea.slohmaier.com/slohmaier/dev-process) anhand einer EPB-Steuergerät-Software. Zeigt ASPICE 4.0 / ISO 26262-konforme Entwicklung im Monorepo: Anforderungen, Architektur, Code, Tests, Reviews, MISRA, Safety Case, Manuals — alles auf einen Pull-Request-Klick verifizierbar, alles in einem Release-Bundle.
Complete demonstration of the [slohmaier Dev Process](https://gitea.slohmaier.com/slohmaier/dev-process) using an EPB ECU software. Shows ASPICE 4.0 / ISO 26262-compliant development in a monorepo: requirements, architecture, code, tests, reviews, MISRA, safety case, manuals — all verifiable in a single pull-request click, all in a single release bundle.
> **🌐 Live-Dashboard:** https://gitea.slohmaier.com/pages/demo-epb/
> Auto-aktualisiert bei jedem Push auf `main` und bei jedem Release-Tag.
> **🌐 Live dashboard:** https://gitea.slohmaier.com/pages/demo-epb/
> Auto-refreshed on every push to `main` and every release tag.
> Diese Software ist **bewusst kein Produktivcode** — sie ist die Demonstration des Engineering-Verfahrens. Code-Umfang bewusst klein, Prozess-Tiefe vollständig.
> This software is **intentionally not production code** — it is a demonstration of the engineering method. Code volume kept small on purpose; process depth complete.
## Was die Demo zeigt
## What the demo shows
| Kategorie | Inhalt |
|-----------|--------|
| **Pläne** (Word) | 5 (PID, PM-, QA-, SWE-, Test-Plan) |
| **Safety-Doku** (Word) | 6 (HARA, Safety Case, FMEDA, MISRA-Compliance, Verification-Report, Tool-Qualification) |
| **Manuals** (Word) | 2 (User-Manual, Service-Manual) |
| **Audit-Artefakte** (Word) | 3 (Review-Protokoll, Non-Conformity, MISRA-Deviation-Record) |
| **System-Anforderungen** | 10 in `reqs/sys/` (Markdown + Doorstop-Style) |
| **Software-Anforderungen** | 25 in `reqs/swe/` |
| **System-Architektur** | 5 in `arch/sys/` mit PlantUML |
| **Software-Architektur** | 10 in `arch/swe/` mit PlantUML |
| **Implementierte C-Komponenten** | 4 (Apply Ctrl D, Safety Mgr D, Actuator Drv B, Switch Db QM) |
| **Stub-Komponenten** | 6 weitere (Header only) |
| **Unit-Tests** | 41, alle grün |
| **CI-Workflows** | 2 (validate + release) |
| **CI-Artefakte** | Coverage HTML, Traceability Matrix, Diagramme SVG, Doxygen, Test-Report, Cppcheck-XML |
| **Cross-Platform-Runner** | Linux + macOS + Windows |
| Category | Content |
|----------|---------|
| **Plans** (Word) | 8 (Project Manual, PID, PM, QA, SWE, Test, CM, RM) |
| **Safety docs** (Word) | 6 (HARA, Safety Case, FMEDA, MISRA Compliance, Verification Report, Tool Qualification) |
| **Manuals** (Word) | 2 (User Manual, Service Manual) |
| **Audit artefacts** (Word) | 3 (Review minutes, Non-Conformity, MISRA Deviation Record) |
| **Safety Goals** | 5 in `safety/sg/` |
| **System Requirements** | 10 in `reqs/sys/` (Markdown + Doorstop style) |
| **Software Requirements** | 25 in `reqs/swe/` |
| **System Architecture** | 5 in `arch/sys/` with PlantUML |
| **Software Architecture** | 10 in `arch/swe/` with PlantUML |
| **Implemented C components** | 4 (Apply Ctrl D, Safety Mgr D, Actuator Drv B, Switch Db QM) |
| **Stub components** | 6 more (header only) |
| **Unit tests** | 46, all green |
| **CI workflows** | 2 (validate + release) |
| **CI artefacts** | Coverage HTML, Traceability Matrix, Diagrams SVG, Doxygen, Test Report, Cppcheck HTML+XML |
| **Cross-platform runners** | Linux + macOS + Windows |
## Quick Start
## Quick start
```bash
git clone https://gitea.slohmaier.com/slohmaier/demo-epb.git
cd demo-epb
# Tests
make test # 41 Tests, alle grün
make test # 46 tests, all green
# Mit Coverage (braucht lcov)
# With coverage (needs lcov)
make coverage
open build/coverage-html/index.html
# Test-Summary-Report (HTML)
# Test summary report (HTML)
make test-report
open build/test-report.html
# Statische Analyse + MISRA (braucht cppcheck)
# Static analysis + MISRA (needs cppcheck)
make static
make misra
# API-Doku (braucht doxygen)
# API doc (needs doxygen)
make docs
open build/api-doc/html/index.html
# Traceability-Matrix (HTML)
# Traceability matrix (HTML)
python3 tools/traceability.py publish docs/traceability
open docs/traceability/index.html
# PlantUML-Diagramme rendern (SVG)
# PlantUML diagrams (SVG)
python3 tools/render_plantuml.py
```
## Geführte Tour (~30 min)
## Guided tour (~30 min)
### 1. Projektplanung (Word)
`docs/`:
- **PID.docx** — Was wird gebaut und warum
- **SWE-Plan.docx** — Sprache, Standards, Branching, Reviews, Coverage-Ziele
- **QA-Plan.docx** — Qualitätsmaßnahmen, Reviews, NC-Management
- **PM-Plan.docx**, **Test-Plan.docx** — Arbeitspakete + Teststrategie
### 1. Project planning (Word)
`docs/plaene/`:
- **Project-Manual.docx** — Navigation guide, reading order, roles
- **PID.docx** — What is built and why
- **SWE-Plan.docx** — Language, standards, branching, reviews, coverage targets
- **QA-Plan.docx** — Quality measures, reviews, NC management
- **PM-Plan.docx, Test-Plan.docx, CM-Plan.docx, RM-Plan.docx**
### 2. Funktionale Sicherheit (Word — `docs/safety/`)
- **HARA.docx** — Hazard Analysis & Risk Assessment. Leitet **ASIL-D** ab.
- **Safety-Case.docx** — Argumentation in GSN-Style, warum die Sicherheitsziele erfüllt sind
- **FMEDA.docx** — Pro-Komponente Failure Modes mit Diagnostic Coverage
- **Tool-Qualification-Cppcheck.docx** — Tool-Qual für Cppcheck (TI2/TD2/TCL2)
- **MISRA-Compliance-Statement.docx** — formaler Compliance-Nachweis
- **Verification-Report.docx** — V-Modell rechte Seite zusammenfassend
### 2. Functional safety (Word — `docs/safety/`)
- **HARA.docx** — Hazard Analysis & Risk Assessment. Derives **ASIL-D**.
- **Safety-Case.docx** — GSN-style argument that safety goals are met
- **FMEDA.docx** — Per-component failure modes with diagnostic coverage
- **Tool-Qualification-Cppcheck.docx** — Tool qual for Cppcheck (TI2/TD2/TCL2)
- **MISRA-Compliance-Statement.docx** — Formal compliance evidence
- **Verification-Report.docx** — V-model right side summary
### 3. Manuals (Word — `docs/manuals/`)
- **User-Manual.docx** — Fahrerhandbuch-Auszug (Apply, Release, Hill-Hold, LED-Codes)
- **Service-Manual.docx** — Werkstatt-Doku mit UDS-DTCs, Service-Modus, Sensor-Prüfung
- **User-Manual.docx** — Driver manual (apply, release, hill-hold, LED codes)
- **Service-Manual.docx** — Workshop doc with UDS DTCs, service mode, sensor checks
### 4. Sicherheits-Logik (das ASIL-D Stück)
Traceability-Kette:
### 4. Safety logic (the ASIL-D piece)
Traceability chain:
```
reqs/sys/SYS-001.md arch/swe/SWA-002.md src/apply_controller.c tests/unit/test_apply_controller.c
safety/sg/SG-001.md → reqs/sys/SYS-001.md → arch/swe/SWA-002.md → src/apply_controller.c tests/unit/test_apply_controller.c
```
### 5. Anforderungen + Architektur (Doorstop in Markdown)
- `reqs/sys/` + `reqs/swe/`Anforderungen mit Mapping
- `arch/sys/` + `arch/swe/`Architektur mit Mapping per `links:` im Frontmatter
- Eingebettete PlantUML-Diagramme rendern direkt in Gitea (UI) und als SVG im Release-Bundle
### 5. Requirements + architecture (Doorstop in Markdown)
- `safety/sg/`, `reqs/sys/` + `reqs/swe/`requirements with mapping
- `arch/sys/` + `arch/swe/`architecture with mapping via `links:` in frontmatter
- Embedded PlantUML diagrams render in Gitea (UI) and as SVG in the release bundle
### 6. Code mit Mapping-Tags
Jede `.c`-Datei trägt `@arch`, `@reqs`, `@asil` im Header:
### 6. Code with mapping tags
Every `.c` file carries `@arch`, `@reqs`, `@asil` in the header:
```c
/**
* @file apply_controller.c
* @arch SWA-002
* @reqs SWE-001 SWE-002 SWE-003 SWE-004
* @reqs SWE-001 SWE-002 SWE-003 SWE-004 SWE-005
*
* ASIL: D.
*/
```
### 7. Tests mit Anforderungs-Tags
`tests/unit/test_*.c` referenziert die Requirements per `@reqs`. Test-Report (`build/test-report.html`) macht das Mapping klickbar sichtbar.
### 7. Tests with requirement tags
`tests/unit/test_*.c` references requirements via `@reqs`. The test report (`build/test-report.html`) makes the mapping clickable.
### 8. Audit-Artefakte
- `docs/reviews/REV-001.docx` — Review-Protokoll für die ASIL-D-Komponente
- `docs/non-conformities/NC-001.docx` — NC mit Korrekturmaßnahme
- `misra/records/MISRA-REC-001.docx` — MISRA Advisory-Deviation
### 8. Audit artefacts
- `docs/reviews/REV-001.docx` — Review minutes for the ASIL-D component
- `docs/non-conformities/NC-001.docx` — NC with corrective action
- `misra/records/MISRA-REC-001.docx` — MISRA advisory deviation
### 9. CI-Pipeline (`.gitea/workflows/validate.yml`)
Bei jedem Push:
1. **Cross-Platform Build + Test** auf Linux + macOS + Windows
2. **Static Analysis** (Cppcheck)
3. **MISRA-Check** (Cppcheck + MISRA-Addon)
### 9. CI pipeline (`.gitea/workflows/validate.yml`)
On every push:
1. **Cross-platform build + test** on Linux + macOS + Windows
2. **Static analysis** (Cppcheck)
3. **MISRA check** (Cppcheck + MISRA addon)
4. **Coverage** (gcov/lcov)
5. **Traceability-Check** (bidirektional)
6. **PlantUML-Render** (alle Diagramme als SVG)
7. **Doxygen-API-Doc**
8. **Test-Summary-Report**
5. **Traceability check** (bidirectional)
6. **PlantUML render** (all diagrams as SVG)
7. **Doxygen API doc**
8. **Test summary report**
Alles als Gitea-Artefakte abrufbar.
All available as Gitea artefacts.
### 10. Release-Workflow (`.gitea/workflows/release.yml`)
Auf Tag-Push `v*.*.*`:
- Vollständigen Build + alle Reports
- Bündelt **Source-Archive + Artefakt-Archive** (CI-Output + alle Word-Docs)
- Erzeugt Gitea-Release mit Release-Notes
### 10. Release workflow (`.gitea/workflows/release.yml`)
On tag push `v*.*.*`:
- Full build + all reports
- Bundles **source archive + artefact archive** (CI output + all Word docs)
- Creates a Gitea release with release notes
Beispiel: https://gitea.slohmaier.com/slohmaier/demo-epb/releases
Example: https://gitea.slohmaier.com/slohmaier/demo-epb/releases
## Architektur-Überblick
## Architecture overview
```
EPB ECU (SA-001)
@@ -150,28 +152,27 @@ Beispiel: https://gitea.slohmaier.com/slohmaier/demo-epb/releases
| Logger (QM) [stub] |
+----------------------------------+
| |
Aktor L (SA-002) Aktor R (SA-002)
Actuator L (SA-002) Actuator R (SA-002)
```
## Format-Strategie
## Format strategy
| Inhalt | Format | Begründung |
|--------|--------|------------|
| Pläne + Safety + Audit + Manuals | **Word** (.docx) | Industriestandard für ISO-9001-Freigabe |
| Requirements + Architektur | **Markdown** (Doorstop-Stil) | Lebendig, diff-bar, Traceability per Skript |
| Code, Tests, CI | C / YAML | klar |
| Release-Bundle | tar.gz mit allem | Eine Datei für den Auditor |
| Content | Format | Rationale |
|---------|--------|-----------|
| Plans + Safety + Audit + Manuals | **Word** (.docx) | Industry standard for ISO 9001 release |
| Requirements + Architecture | **Markdown** (Doorstop style) | Lives daily, diff-able, traceability by script |
| Code, Tests, CI | C / YAML | obvious |
| Release bundle | tar.gz with everything | One file for the auditor |
Markdown ist Source of Truth, Word wird per pandoc daraus gebaut.
Markdown is the source of truth; Word is built via pandoc.
## Referenzen
## References
- [slohmaier/dev-process](https://gitea.slohmaier.com/slohmaier/dev-process) — Methodik-Repo
- [slohmaier/dev-process](https://gitea.slohmaier.com/slohmaier/dev-process) — Methodology repo
- ASPICE 4.0
- ISO 26262 (insbesondere Part 2, 3, 5, 6, 8, 10)
- ISO 26262 (in particular Part 2, 3, 5, 6, 8, 10)
- MISRA C:2012
## Lizenz
## Licence
MIT — siehe [LICENSE](LICENSE).
Tue May 12 02:28:37 PDT 2026
MIT — see [LICENSE](LICENSE).