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](https://gitea.slohmaier.com/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.

```markdown
---
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:

```c
/**
 * @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:
```bash
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

```bash
# 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:
   ```bash
   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.