slohmaier/dev-process
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(i18n): dev-process repo in English

Browse Source 
- README.md: full English rewrite
- All 13 vorlagen MD templates hand-translated:
  PID, PM-Plan, QA-Plan, SWE-Plan, Test-Plan,
  SA, SWA, Review-Protokoll, Non-Conformity,
  MISRA-Deviation-Permit, MISRA-Deviation-Record,
  Traceability-Matrix, angebot (quotation)
- Master Word template (slohmaier-doc-template.docx) regenerated
  in English: cover page, document control, TOC headers,
  classification banner all English
- All derived Word vorlagen regenerated from English MD sources

Still to translate: toolstack.md, gitea-aspice-setup.md
This commit is contained in:
Stefan Lohmaier
2026-05-12 03:42:35 -07:00
parent 6e458ae76f
commit d5cfec9e42
25 changed files with 774 additions and 875 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+88 -88
View File
@@ -1,41 +1,41 @@
# 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.
A practical development process aligned with ASPICE 4.0 / ISO 26262, implemented with Gitea, Doorstop, MS Word, and VS Code. Designed for freelance projects and small teams.
**Demo-Projekt:** [slohmaier/demo-epb](https://gitea.slohmaier.com/slohmaier/demo-epb) — Elektrische Parkbremse, wendet diesen Prozess vollständig an.
**Demo project:** [slohmaier/demo-epb](https://gitea.slohmaier.com/slohmaier/demo-epb) — Electric Parking Brake, applies this process end-to-end.
## Grundprinzip
## Core principle
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.
Everything lives in a **monorepo**. Requirements, documents, code, and tests sit together in one Git repository. All changes go through pull requests with approval — that's the formal review record.
## Format-Strategie: Hybrid
## Format strategy: hybrid
Die zwei Welten — ISO-9001-Audit und tägliches Engineering — haben unterschiedliche Anforderungen. Wir trennen sauber:
The two worlds — ISO-9001 audits vs day-to-day engineering — have different needs. We split cleanly:
| 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 |
| Artifact | Format | Rationale |
|----------|--------|-----------|
| PID, PM Plan, QA Plan, SWE Plan, Test Plan | **Word** (signed) | Formally released, delivered to customers |
| Reviews, non-conformities, audit minutes | **Word** | Audit artifacts |
| MISRA permits / records | **Word** | Audit artifacts |
| Quotations, contracts | **Word** | obvious |
| Requirements (SYS, SWE) | **Markdown** (Doorstop) | Diff, traceability, lives daily |
| Architecture (SA, SWA, SWD) | **Markdown** (Doorstop) | Mapping via `links:` |
| Code, tests, CI | source | obvious |
| Customer-facing PDFs | **PDF via pandoc** from MD | formal handover of engineering artifacts |
**Markdown-Vorlagen sind Source of Truth**, Word wird daraus per pandoc gebaut (`tools/generate_word_vorlagen.sh`).
**Markdown templates are the source of truth**; Word is built from them via pandoc (`tools/generate_word_vorlagen.sh`).
## Monorepo-Struktur
## Monorepo structure
```
projekt-name/
project-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)
swd/ SWD-001.md (ASPICE SWE.3, ASIL-C+)
docs/
PID.md
PM-Plan.md
@@ -44,7 +44,7 @@ projekt-name/
Test-Plan.md
reviews/
non-conformities/
traceability/ (generiert von Doorstop)
traceability/ (generated by Doorstop)
src/
tests/
unit/
@@ -59,9 +59,9 @@ projekt-name/
.doorstop.yml
```
## Anforderungen mit Doorstop (Markdown-Modus)
## Requirements with Doorstop (markdown mode)
Requirements sind `.md`-Dateien mit YAML-Frontmatter. PlantUML-Diagramme direkt einbettbar.
Requirements are `.md` files with YAML frontmatter. PlantUML diagrams embed directly.
```markdown
---
@@ -71,9 +71,9 @@ links:
- SYS-001: abc123
---
# SWE-001: CAN Bus Initialisierung
# SWE-001: CAN Bus Initialization
Der CAN-Treiber muss den Bus mit konfigurierbarer Baudrate initialisieren.
The CAN driver must initialize the bus with configurable baud rate.
```plantuml
@startuml
@@ -84,22 +84,22 @@ Hardware --> CANDriver: ok
```
```
Gitea rendert das direkt. VS Code mit PlantUML-Extension zeigt die Preview beim Editieren.
Gitea renders this natively. VS Code with the PlantUML extension shows a live preview.
Doorstop prüft:
- Alle Links valide
- Alle Requirements haben Tests
- Keine Lücken in der Traceability
Doorstop verifies:
- All links resolve
- All requirements have tests
- No gaps in traceability
## Architektur-Design (ASPICE SYS.3 / SWE.2)
## Architecture 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.
Architecture elements live in `arch/` and are also Doorstop documents. Same mechanism as requirements: Markdown + YAML frontmatter + embedded 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)
- `arch/sys/SA-XXX.md` — system architecture, mapping to SYS requirements
- `arch/swe/SWA-XXX.md` — software architecture, mapping to SWE requirements
- `arch/swd/SWD-XXX.md` — software detailed design (ASIL-C+ only)
**Mapping** geschieht über `links:` im Frontmatter:
**Mapping** via `links:` in frontmatter:
```markdown
---
@@ -113,12 +113,12 @@ links:
# 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
`doorstop check` verifies bidirectionally:
- Every SWE requirement is covered by at least one SWA element
- Every SWA element points to at least one SWE requirement
- `doorstop publish all docs/traceability/` produces the traceability matrix
**Code → Architektur** per Header-Kommentar im Modul:
**Code → architecture** via header comment:
```c
/**
@@ -128,82 +128,82 @@ links:
*/
```
Vorlagen: `vorlagen/SA-vorlage.md`, `vorlagen/SWA-vorlage.md`.
Templates: `vorlagen/SA-vorlage.md`, `vorlagen/SWA-vorlage.md`.
## Reviews
Jede Änderung — an Code, Requirements, Dokumenten oder Plänen — geht über einen Pull Request.
Every change — to code, requirements, documents, or plans — goes through a 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 |
| Item | Approver |
|------|----------|
| New / changed requirement | ≥ 1 reviewer |
| Architecture element (SA/SWA/SWD) | ≥ 2 technical reviewers |
| Document (plan, minutes) | ≥ 1 reviewer |
| Code change | ≥ 1 reviewer |
| MISRA permit | technical lead |
Merge = formale Freigabe. Git-History ist der Audit-Trail.
Merge = formal release. Git history is the audit trail.
## Traceability
Vier Ebenen werden verknüpft:
Four levels are linked:
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`
1. **Doorstop links** in `.md` files: `links: [SYS-001: abc123]`
2. **Architecture mapping** (arch element → requirement) also via Doorstop
3. **Commit messages**: `feat(SWE-001): implement CAN init` or `feat(SWA-003): ...`
4. **Issue references** in PRs: `Refs #42`
Chain: `SYS-XXX → SA-XXX → SWE-XXX → SWA-XXX → Code → Test`
Chain: `SYS-XXX → SA-XXX → SWE-XXX → SWA-XXX → code → test`
Doorstop erzeugt automatisch einen Traceability-Report:
Doorstop generates the matrix automatically:
```bash
doorstop publish all docs/traceability/
```
## CI-Pipeline
## CI pipeline
Läuft bei jedem Push und PR automatisch:
Runs on every push and PR:
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
1. `doorstop check` — requirement links valid
2. `cppcheck --addon=misra` — MISRA compliance
3. `make test` — unit tests
4. `make coverage` — coverage report
5. `doorstop publish` — refresh traceability report
## Dateien in diesem Repo
## Files in this 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 |
| Path | Content |
|------|---------|
| `toolstack/toolstack.md` | Complete tool stack |
| `gitea-aspice-setup.md` | Setting up Gitea for ASPICE |
| `dev-process-schaubild.html` | V-model infographic |
| `vorlagen/` | Markdown templates (source of truth) |
| `vorlagen-word/` | Generated Word templates + master template `slohmaier-doc-template.docx` |
| `tools/build_word_template.py` | Builds the neutral Word master template with styles, cover page, document control |
| `tools/generate_word_vorlagen.sh` | Builds the `.docx` versions from the `.md` templates via pandoc |
## Word-Vorlagen neu generieren
## Regenerate Word templates
```bash
# Master-Template + alle abgeleiteten Word-Vorlagen neu bauen
# Rebuild master template + all derived Word templates
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
The master template is ISO-9001-compliant and includes:
- Cover page with project, document ID, version, classification
- Document control (approvals, revision history, distribution)
- Auto-tables of contents, figures, and tables
- Styles for H1–H4, Body, Code, Note, Warning, Requirement
- Header/footer with project, document ID, classification, page number
## Einsatz in eigenen Projekten
## Using this process in your own projects
Drei Wege, diesen Prozess zu nutzen:
Three options:
1. **Git-Submodule** in dein Projekt:
1. **Git submodule** in your project:
```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.
2. **Copy templates** into the project and commit (static snapshot).
3. **Fork / clone** and use as the base for your own customisations.