dev-process/README.md

slohmaier Dev Process

Ein praxisnaher Entwicklungsprozess angelehnt an ASPICE 4.0 / ISO 26262, umgesetzt mit Gitea, Doorstop, MS Word und VS Code. Ausgelegt für Freelance-Projekte und kleine Teams.

Demo-Projekt: slohmaier/demo-epb — Elektrische Parkbremse, wendet diesen Prozess vollständig an.

Grundprinzip

Alles lebt in einem Monorepo. Anforderungen, Dokumente, Code und Tests sind zusammen in einem Git-Repository. Alle Änderungen gehen über Pull Requests mit Approval — das ist der formale Review-Nachweis.

Format-Strategie: Hybrid

Die zwei Welten — ISO-9001-Audit und tägliches Engineering — haben unterschiedliche Anforderungen. Wir trennen sauber:

Artefakt	Format	Begründung
PID, PM-Plan, QA-Plan, SWE-Plan, Test-Plan	Word (signiert)	Formell freigegeben, an Kunden geliefert
Reviews, Non-Conformities, Audit-Protokolle	Word	Audit-Artefakte
MISRA Permits / Records	Word	Audit-Artefakte
Angebote, Verträge	Word	klar
Requirements (SYS, SWE)	Markdown (Doorstop)	Diff, Traceability, lebt täglich
Architektur (SA, SWA, SWD)	Markdown (Doorstop)	Mapping per links:
Code, Tests, CI	Code	klar
Liefer-PDFs an Kunden	PDF via pandoc aus MD	formelle Übergabe der Engineering-Artefakte

Markdown-Vorlagen sind Source of Truth, Word wird daraus per pandoc gebaut (tools/generate_word_vorlagen.sh).

Monorepo-Struktur

projekt-name/
  reqs/
    sys/        SYS-001.md, SYS-002.md
    swe/        SWE-001.md, SWE-002.md
  arch/
    sys/        SA-001.md, SA-002.md          (ASPICE SYS.3)
    swe/        SWA-001.md, SWA-002.md        (ASPICE SWE.2)
    swd/        SWD-001.md                    (ASPICE SWE.3, ab ASIL-C)
  docs/
    PID.md
    PM-Plan.md
    QA-Plan.md
    SWE-Plan.md
    Test-Plan.md
    reviews/
    non-conformities/
    traceability/       (generiert von Doorstop)
  src/
  tests/
    unit/
    integration/
    results/
  misra/
    permits/
    records/
    reports/
  .gitea/
    workflows/validate.yml
  .doorstop.yml

Anforderungen mit Doorstop (Markdown-Modus)

Requirements sind .md-Dateien mit YAML-Frontmatter. PlantUML-Diagramme direkt einbettbar.

---
active: true
level: 1.0
links:
  - SYS-001: abc123
---

# SWE-001: CAN Bus Initialisierung

Der CAN-Treiber muss den Bus mit konfigurierbarer Baudrate initialisieren.

```plantuml
@startuml
ECU -> CANDriver: init(baudrate)
CANDriver -> Hardware: configure(baudrate)
Hardware --> CANDriver: ok
@enduml

Gitea rendert das direkt. VS Code mit PlantUML-Extension zeigt die Preview beim Editieren.

Doorstop prüft:
- Alle Links valide
- Alle Requirements haben Tests
- Keine Lücken in der Traceability

## Architektur-Design (ASPICE SYS.3 / SWE.2)

Architektur-Elemente liegen in `arch/` und sind ebenfalls Doorstop-Dokumente. Gleiche Mechanik wie Anforderungen: Markdown + YAML-Frontmatter + eingebettetes PlantUML.

- `arch/sys/SA-XXX.md` — System-Architektur, Mapping auf SYS-Anforderungen
- `arch/swe/SWA-XXX.md` — Software-Architektur, Mapping auf SWE-Anforderungen
- `arch/swd/SWD-XXX.md` — Software Detailed Design (nur ab ASIL-C)

**Mapping** geschieht über `links:` im Frontmatter:

```markdown
---
active: true
level: 1.0
links:
  - SWE-001: abc123
  - SWE-014: def456
---

# SWA-003: CAN Driver Component

doorstop check verifiziert in beide Richtungen:

• Jede SWE-Anforderung wird von mindestens einem SWA-Element abgedeckt
• Jedes SWA-Element verweist auf mindestens eine SWE-Anforderung
• doorstop publish all docs/traceability/ erzeugt die Traceability-Matrix

Code → Architektur per Header-Kommentar im Modul:

/**
 * @file can_driver.c
 * @arch SWA-003
 * @reqs SWE-001, SWE-014
 */

Vorlagen: vorlagen/SA-vorlage.md, vorlagen/SWA-vorlage.md.

Reviews

Jede Änderung — an Code, Requirements, Dokumenten oder Plänen — geht über einen Pull Request.

Was	Approver
Requirement neu/ändern	mind. 1 Reviewer
Architektur-Element (SA/SWA/SWD)	mind. 2 Technical Reviewer
Dokument (Plan, Protokoll)	mind. 1 Reviewer
Code-Änderung	mind. 1 Reviewer
MISRA Permit	Technical Lead

Merge = formale Freigabe. Git-History ist der Audit-Trail.

Traceability

Vier Ebenen werden verknüpft:

1. Doorstop-Links in .md-Dateien: links: [SYS-001: abc123]
2. Architektur-Mapping (Arch-Element → Anforderung) ebenfalls per Doorstop
3. Commit-Messages: feat(SWE-001): implement CAN init oder feat(SWA-003): ...
4. Issue-Referenzen in PRs: Refs #42

Chain: SYS-XXX → SA-XXX → SWE-XXX → SWA-XXX → Code → Test

Doorstop erzeugt automatisch einen Traceability-Report:

doorstop publish all docs/traceability/

CI-Pipeline

Läuft bei jedem Push und PR automatisch:

1. doorstop check — Requirements-Links valide
2. cppcheck --addon=misra — MISRA-Compliance
3. make test — Unit Tests
4. make coverage — Coverage-Report
5. doorstop publish — Traceability-Report aktualisieren

Dateien in diesem Repo

Pfad	Inhalt
toolstack/toolstack.md	Vollständiger Tool-Stack
gitea-aspice-setup.md	Gitea einrichten für ASPICE
dev-process-schaubild.html	V-Modell Infografik
vorlagen/	Markdown-Vorlagen (Source of Truth)
vorlagen-word/	Generierte Word-Vorlagen + Master-Template slohmaier-doc-template.docx
tools/build_word_template.py	Erzeugt das neutrale Master-Word-Template mit Formatvorlagen, Deckblatt, Document Control
tools/generate_word_vorlagen.sh	Erzeugt aus den .md-Vorlagen die .docx-Versionen via pandoc

Word-Vorlagen neu generieren

# Master-Template + alle abgeleiteten Word-Vorlagen neu bauen
python3 tools/build_word_template.py
bash tools/generate_word_vorlagen.sh

Das Master-Template enthält ISO-9001-konform:

• Deckblatt mit Projekt, Dokument-ID, Version, Klassifikation
• Document Control (Freigaben, Änderungshistorie, Verteiler)
• Auto-Verzeichnisse (Inhalt, Abbildungen, Tabellen)
• Formatvorlagen für H1–H4, Body, Code, Note, Warning, Requirement
• Header/Footer mit Projekt, Dokument-ID, Klassifikation, Seitennummer

Einsatz in eigenen Projekten

Drei Wege, diesen Prozess zu nutzen:

1. Git-Submodule in dein Projekt:

   git submodule add https://gitea.slohmaier.com/slohmaier/dev-process .dev-process
   

2. Vorlagen kopieren und im Projekt einchecken (statischer Snapshot).
3. Fork / Clone und als Basis für eigene Anpassungen verwenden.