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

feat(i18n): toolstack.md + gitea-aspice-setup.md in English

Browse Source 
Last German files in the dev-process repo translated:
- toolstack/toolstack.md: tool overview, categories, descriptions
- gitea-aspice-setup.md: complete setup guide for Gitea + ASPICE

dev-process repo is now fully in English.
This commit is contained in:
Stefan Lohmaier
2026-05-12 03:43:36 -07:00
parent d5cfec9e42
commit 54e7decd9c
2 changed files with 181 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files
gitea-aspice-setup.md
+77 -77
View File
@@ -1,10 +1,10 @@
# Gitea für ASPICE 4.0 einrichten # Setting up Gitea for ASPICE 4.0
Konkrete Anleitung für den slohmaier Dev Process auf Basis von Gitea, Doorstop und Gitea Actions. Concrete setup guide for the slohmaier Dev Process on top of Gitea, Doorstop, and Gitea Actions.
## Gitea installieren ## Install Gitea
### Docker (empfohlen) ### Docker (recommended)
```yaml ```yaml
# docker-compose.yml # docker-compose.yml
@@ -26,7 +26,7 @@ services:
docker compose up -d docker compose up -d
``` ```
### PlantUML-Rendering aktivieren ### Enable PlantUML rendering
In `data/gitea/conf/app.ini`: In `data/gitea/conf/app.ini`:
@@ -39,7 +39,7 @@ RENDER_COMMAND = plantuml -tsvg -pipe
IS_INPUT_FILE = false IS_INPUT_FILE = false
``` ```
Oder über den öffentlichen Renderer (kein lokales PlantUML nötig): Or via the public renderer (no local PlantUML needed):
```ini ```ini
[server] [server]
@@ -51,85 +51,85 @@ NEED_POSTPROCESS = true
RENDER_COMMAND = curl -s https://www.plantuml.com/plantuml/svg/~h RENDER_COMMAND = curl -s https://www.plantuml.com/plantuml/svg/~h
``` ```
## Organisations- und Repo-Struktur ## Organisation and repo structure
``` ```
Organisation: slohmaier (eigene Projekte) Organisation: slohmaier (own projects)
Organisation: kunde-projektname (Kundenprojekte) Organisation: client-projectname (customer projects)
Repo: projektname (Monorepo: reqs + docs + src + tests) Repo: projectname (monorepo: reqs + docs + src + tests)
``` ```
Ein Repo pro Projekt. Kein Aufteilen in viele Repos. One repo per project. Do not split into many repos.
## Label-Schema ## Label scheme
Alle Labels in der Organisation anlegen, dann in jedem Repo verfügbar. Create all labels at the organisation level, then they are available in every repo.
| Label | Farbe | Verwendung | | Label | Colour | Use |
|-------|-------|------------| |-------|--------|-----|
| `type:requirement` | blau | Anforderungs-Issue | | `type:requirement` | blue | Requirement issue |
| `type:architecture` | dunkelblau | Architektur-Entscheidung | | `type:architecture` | dark blue | Architecture decision |
| `type:implementation` | grün | Implementierungsaufgabe | | `type:implementation` | green | Implementation task |
| `type:test` | hellgrün | Testfall | | `type:test` | light green | Test case |
| `type:document` | grau | Dokument-Änderung | | `type:document` | grey | Document change |
| `aspice:NC` | rot | Non-Conformity | | `aspice:NC` | red | Non-conformity |
| `aspice:change-request` | orange | Change Request | | `aspice:change-request` | orange | Change request |
| `aspice:finding` | gelb | QA-Finding | | `aspice:finding` | yellow | QA finding |
| `status:review-required` | lila | Wartet auf Review | | `status:review-required` | purple | Waiting for review |
| `status:approved` | grün | Freigegeben | | `status:approved` | green | Approved |
| `severity:critical` | dunkelrot | Kritisch | | `severity:critical` | dark red | Critical |
| `severity:major` | orange | Schwerwiegend | | `severity:major` | orange | Major |
| `severity:minor` | gelb | Geringfügig | | `severity:minor` | yellow | Minor |
## Branch-Schutz ## Branch protection
Für `main`: For `main`:
- Kein direktes Pushen - No direct pushing
- Mind. 1 Approval erforderlich - At least 1 approval required
- CI muss grün sein - CI must be green
Einstellbar unter: Repo → Settings → Branches → Branch Protection Configurable under: Repo → Settings → Branches → Branch Protection
## Branching-Strategie ## Branching strategy
``` ```
main protected, stabil, nur via PR main protected, stable, only via PR
develop Integrationsbranch develop integration branch
feature/SWE-001-can-init Feature mit Req-Referenz feature/SWE-001-can-init feature with requirement reference
docs/qa-plan-v1 Dokument-Änderung docs/qa-plan-v1 document change
fix/NC-003-misra-violation Bugfix mit NC-Referenz fix/NC-003-misra-violation bug fix with NC reference
release/v1.0 Release-Branch release/v1.0 release branch
``` ```
## PR/Review-Workflow ## PR / review workflow
### Neue Anforderung anlegen ### Create a new requirement
``` ```
1. Branch: reqs/SWE-001-can-init 1. Branch: reqs/SWE-001-can-init
2. Datei anlegen: reqs/swe/SWE-001.md 2. Create file: reqs/swe/SWE-001.md
3. PR erstellen mit Titel: "[REQ] SWE-001: CAN Bus Initialisierung" 3. Create PR titled: "[REQ] SWE-001: CAN Bus Initialization"
4. Reviewer zuweisen 4. Assign reviewer
5. Nach Approval → Merge 5. After approval → merge
``` ```
### Dokument ändern ### Change a document
``` ```
1. Branch: docs/qa-plan-update 1. Branch: docs/qa-plan-update
2. Änderung in docs/QA-Plan.md 2. Change in docs/QA-Plan.md
3. PR mit Beschreibung der Änderung 3. PR with description of the change
4. Reviewer zuweisen → Approval → Merge 4. Assign reviewer → approval → merge
``` ```
### Code-Änderung ### Code change
``` ```
1. Branch: feature/SWE-001-can-init 1. Branch: feature/SWE-001-can-init
2. Commit-Message: "feat(SWE-001): implement CAN bus init at configurable baudrate" 2. Commit message: "feat(SWE-001): implement CAN bus init at configurable baudrate"
3. PR: "Refs #<issue-nummer>" 3. PR: "Refs #<issue-number>"
4. CI muss grün sein 4. CI must be green
5. Reviewer → Approval → Merge 5. Reviewer → approval → merge
``` ```
## Commit-Message-Konvention ## Commit-message convention
``` ```
feat(SWE-001): implement CAN bus initialization feat(SWE-001): implement CAN bus initialization
@@ -138,9 +138,9 @@ docs(QA-Plan): add review schedule for SWE phase
test(SWE-001): add unit test for CAN init error handling test(SWE-001): add unit test for CAN init error handling
``` ```
Format: `<type>(<id>): <beschreibung>` Format: `<type>(<id>): <description>`
## Gitea Actions — Basis-Pipeline ## Gitea Actions — basic pipeline
```yaml ```yaml
# .gitea/workflows/validate.yml # .gitea/workflows/validate.yml
@@ -183,9 +183,9 @@ jobs:
git push git push
``` ```
## Doorstop konfigurieren ## Configure Doorstop
`.doorstop.yml` im Repo-Root: `.doorstop.yml` at the repo root:
```yaml ```yaml
settings: settings:
@@ -193,7 +193,7 @@ settings:
prefix: REQ prefix: REQ
``` ```
`.doorstop` in jedem Requirements-Unterordner: `.doorstop` in each requirements subfolder:
```yaml ```yaml
# reqs/sys/.doorstop # reqs/sys/.doorstop
@@ -219,24 +219,24 @@ settings:
parent: SWE parent: SWE
``` ```
## VS Code Extensions für diesen Stack ## VS Code extensions for this stack
| Extension | ID | Zweck | | Extension | ID | Purpose |
|-----------|-----|-------| |--------------------|------------------------------|-------------------------------|
| PlantUML | jnbt.plantuml | Diagramm-Preview in Markdown | | PlantUML | jnbt.plantuml | Diagram preview in Markdown |
| Markdown All in One | yzhang.markdown-all-in-one | Markdown-Bearbeitung | | Markdown All in One| yzhang.markdown-all-in-one | Markdown editing |
| YAML | redhat.vscode-yaml | YAML-Frontmatter in .md | | YAML | redhat.vscode-yaml | YAML frontmatter in .md |
| GitLens | eamodio.gitlens | Git-History und Blame | | GitLens | eamodio.gitlens | Git history and blame |
| Continue | Continue.continue | KI-Assistent lokal via Ollama | | Continue | Continue.continue | AI assistant, local via Ollama|
## Traceability-Übersicht ## Traceability overview
``` ```
SYS-001 (System-Anforderung) SYS-001 (system requirement)
└── SWE-001 (Software-Anforderung) [links: SYS-001] └── SWE-001 (software requirement) [links: SYS-001]
└── TST-001 (Testfall) [links: SWE-001] └── TST-001 (test case) [links: SWE-001]
└── Commit abc1234 [feat(SWE-001): ...] └── commit abc1234 [feat(SWE-001): ...]
└── PR #12 [Refs #5 (Issue: SWE-001)] └── PR #12 [Refs #5 (Issue: SWE-001)]
``` ```
Doorstop prüft die komplette Kette automatisch bei jedem CI-Lauf. Doorstop verifies the complete chain automatically on every CI run.
toolstack/toolstack.md
+104 -104
View File
@@ -1,57 +1,57 @@
# Toolstack – slohmaier Dev Process # Toolstack – slohmaier Dev Process
Kompletter Open-Source-Toolstack fuer ASPICE 4.0 und ISO 26262 konforme Embedded-Entwicklung. Complete open-source toolstack for ASPICE 4.0 and ISO 26262-compliant embedded development.
--- ---
## Uebersicht ## Overview
| Kategorie | Tool | Bemerkung | | Category | Tool | Notes |
|-----------|------|-----------| |-----------|------|-------|
| Source Control | Gitea (self-hosted) | `tea` CLI fuer Kommandozeile, VS Code Integration | | Source Control | Gitea (self-hosted) | `tea` CLI for command line, VS Code integration |
| Requirements | Doorstop (Markdown-Modus) | Requirements als `.md` mit PlantUML eingebettet | | Requirements | Doorstop (Markdown mode) | Requirements as `.md` with embedded PlantUML |
| Architektur-Design | Doorstop + PlantUML | SA / SWA / SWD als `.md` mit Mapping per `links:` (ASPICE SYS.3 / SWE.2 / SWE.3) | | Architecture design | Doorstop + PlantUML | SA / SWA / SWD as `.md` with mapping via `links:` (ASPICE SYS.3 / SWE.2 / SWE.3) |
| Diagramme | PlantUML | Eingebettet in Markdown, gerendert von Gitea und VS Code | | Diagrams | PlantUML | Embedded in Markdown, rendered by Gitea and VS Code |
| MISRA | Cppcheck + MISRA-Addon | Kostenlos, Deviation Permits/Records via Doorstop | | MISRA | Cppcheck + MISRA addon | Free, deviation permits/records via Doorstop |
| Coverage | gcov/lcov | Bis ASIL-B; MCDC-Star fuer ASIL-C/D | | Coverage | gcov/lcov | Up to ASIL-B; MCDC-Star for ASIL-C/D |
| Unit Tests | CppUTest oder Google Test | Je nach Projekt | | Unit tests | CppUTest or Google Test | Project-dependent |
| Static Analysis | Cppcheck, clang-tidy | Cppcheck auch fuer MISRA | | Static analysis | Cppcheck, clang-tidy | Cppcheck also for MISRA |
| Build | SCons, CMake | Je nach Projekt | | Build | SCons, CMake | Project-dependent |
| Compiler | GCC ARM | Eigene Qualifizierung; Ferrocene fuer Rust | | Compiler | GCC ARM | Own qualification; Ferrocene for Rust |
| CI | Gitea Actions | Pipeline im Monorepo unter `.gitea/workflows/` | | CI | Gitea Actions | Pipeline in the monorepo under `.gitea/workflows/` |
| Open Source Analyse | ScanCode, FOSSology | Lizenz-Compliance | | Open-source analysis | ScanCode, FOSSology | License compliance |
| KI-Unterstuetzung | Continue.dev + Ollama | VS Code Extension, lokal, kein Cloud-Datenschutzproblem | | AI assistance | Continue.dev + Ollama | VS Code extension, local, no cloud privacy issue |
| Dokumentenexport | pandoc | Markdown nach PDF | | Document export | pandoc | Markdown to PDF |
| Editor | VS Code | Primaerer Editor fuer alles | | Editor | VS Code | Primary editor for everything |
--- ---
## Source Control: Gitea ## Source Control: Gitea
Gitea ist eine self-hosted Git-Plattform. Leichtgewichtig, laeuft auf jeder Hardware. Gitea is a self-hosted Git platform. Lightweight, runs on any hardware.
- Web-UI fuer PRs, Reviews, Issues - Web UI for PRs, reviews, issues
- Gitea Actions fuer CI/CD (kompatibel mit GitHub Actions Syntax) - Gitea Actions for CI/CD (compatible with GitHub Actions syntax)
- PlantUML-Rendering in Markdown (per PlantUML-Server) - PlantUML rendering in Markdown (via PlantUML server)
- `tea` CLI fuer Kommandozeilen-Workflows - `tea` CLI for command-line workflows
- Branch Protection und Approval-Workflows - Branch protection and approval workflows
Setup-Anleitung: `gitea-aspice-setup.md` Setup guide: `gitea-aspice-setup.md`
--- ---
## Requirements: Doorstop (Markdown-Modus) ## Requirements: Doorstop (Markdown mode)
Doorstop verwaltet Requirements als `.md`-Dateien mit YAML-Frontmatter. Kein proprietaeres Format, alles lesbar in jedem Editor. Doorstop manages requirements as `.md` files with YAML frontmatter. No proprietary format — everything readable in any editor.
**Vorteile:** **Advantages:**
- Requirements sind Markdown, versioniert in Git - Requirements are Markdown, versioned in Git
- PlantUML-Diagramme direkt im Requirement eingebettet - PlantUML diagrams embedded directly in the requirement
- Traceability-Pruefung per CLI: `doorstop check` - Traceability check via CLI: `doorstop check`
- Report-Generierung: `doorstop publish all docs/traceability/` - Report generation: `doorstop publish all docs/traceability/`
- Gitea rendert alles direkt (Markdown + PlantUML) - Gitea renders everything natively (Markdown + PlantUML)
**Requirement-Format:** **Requirement format:**
```markdown ```markdown
--- ---
@@ -61,162 +61,162 @@ links:
- SYS-001: abc123 - SYS-001: abc123
--- ---
# SWE-001: Titel # SWE-001: Title
Beschreibung mit eingebettetem PlantUML. Description with embedded PlantUML.
``` ```
--- ---
## Architektur-Design: Doorstop + PlantUML ## Architecture design: Doorstop + PlantUML
Architektur-Elemente sind ebenfalls Doorstop-Dokumente, nur mit eigenen Prefixen: Architecture elements are also Doorstop documents, only with their own prefixes:
| Prefix | Ebene | ASPICE | Verzeichnis | | Prefix | Layer | ASPICE | Directory |
|--------|--------------------------------|--------|--------------| |--------|--------------------------------|--------|--------------|
| SA | System Architectural Design | SYS.3 | `arch/sys/` | | SA | System Architectural Design | SYS.3 | `arch/sys/` |
| SWA | Software Architectural Design | SWE.2 | `arch/swe/` | | SWA | Software Architectural Design | SWE.2 | `arch/swe/` |
| SWD | Software Detailed Design | SWE.3 | `arch/swd/` | | SWD | Software Detailed Design | SWE.3 | `arch/swd/` |
**Mapping auf Anforderungen** per `links:` im YAML-Frontmatter — identisch zur Requirements-Verlinkung. Doorstop verifiziert in beide Richtungen: keine verwaisten Anforderungen, keine verwaisten Architektur-Elemente. **Mapping to requirements** via `links:` in the YAML frontmatter — identical to requirements linking. Doorstop verifies in both directions: no orphan requirements, no orphan architecture elements.
**Verifikation in der CI:** **Verification in CI:**
```bash ```bash
doorstop check # bidirektional, schlaegt fehl bei Luecken doorstop check # bidirectional, fails on gaps
doorstop publish all docs/traceability/ # Traceability-Matrix erzeugen doorstop publish all docs/traceability/ # generate traceability matrix
``` ```
Vorlagen unter `dev-process/vorlagen/`: Templates under `dev-process/vorlagen/`:
- `SA-vorlage.md` — System Architecture Element - `SA-vorlage.md` — System Architecture Element
- `SWA-vorlage.md` — Software Architecture Element - `SWA-vorlage.md` — Software Architecture Element
SWD wird nur fuer ASIL-C/D zwingend gefuehrt; fuer QM/A/B reichen Code + Header-Kommentare. SWD is only mandatory for ASIL-C/D; for QM/A/B, code + header comments are sufficient.
--- ---
## Diagramme: PlantUML ## Diagrams: PlantUML
PlantUML-Diagramme werden direkt in Markdown eingebettet. Kein separates Tool, kein Export. PlantUML diagrams are embedded directly in Markdown. No separate tool, no export.
**Rendering:** **Rendering:**
- Gitea: Automatisch via PlantUML-Server (Konfiguration in `app.ini`) - Gitea: automatically via the PlantUML server (configuration in `app.ini`)
- VS Code: PlantUML-Extension (jebbs.plantuml) fuer Live-Preview - VS Code: PlantUML extension (jebbs.plantuml) for live preview
- Export: pandoc mit PlantUML-Filter fuer PDF - Export: pandoc with PlantUML filter for PDF
--- ---
## MISRA: Cppcheck + MISRA-Addon ## MISRA: Cppcheck + MISRA addon
Cppcheck mit MISRA-Addon prueft C-Code auf MISRA-Konformitaet. Kostenlos, laeuft in der CI-Pipeline. Cppcheck with the MISRA addon checks C code for MISRA compliance. Free, runs in the CI pipeline.
```bash ```bash
cppcheck --addon=misra --error-exitcode=1 src/ cppcheck --addon=misra --error-exitcode=1 src/
``` ```
Deviation Permits und Records werden als Markdown-Dateien im `misra/`-Verzeichnis verwaltet. Vorlagen unter `dev-process/vorlagen/`. Deviation permits and records are kept as Markdown files in the `misra/` directory. Templates under `dev-process/vorlagen/`.
--- ---
## Coverage ## Coverage
| ASIL | Tool | Methode | | ASIL | Tool | Method |
|------|------|---------| |------|-----------|-------------------------------|
| A–B | gcov/lcov | Statement + Branch Coverage | | A–B | gcov/lcov | Statement + branch coverage |
| C–D | MCDC-Star | MC/DC Coverage | | C–D | MCDC-Star | MC/DC coverage |
Coverage-Reports werden in der CI generiert und unter `tests/results/` abgelegt. Coverage reports are generated in CI and stored under `tests/results/`.
--- ---
## Unit Tests ## Unit tests
CppUTest oder Google Test, je nach Projektanforderung. CppUTest or Google Test, depending on project requirements.
- Tests unter `tests/unit/` - Tests under `tests/unit/`
- Ergebnisse unter `tests/results/` - Results under `tests/results/`
- CI fuehrt Tests bei jedem Push aus - CI runs tests on every push
--- ---
## Static Analysis ## Static analysis
| Tool | Zweck | | Tool | Purpose |
|------|-------| |------------|----------------------------------------|
| Cppcheck | Allgemeine statische Analyse + MISRA | | Cppcheck | General static analysis + MISRA |
| clang-tidy | Modernisierung, Stil, Bugs | | clang-tidy | Modernisation, style, bugs |
Beide laufen in der CI-Pipeline. Both run in the CI pipeline.
--- ---
## Build: SCons / CMake ## Build: SCons / CMake
Je nach Projekt SCons oder CMake. Cross-Compilation fuer ARM-Targets. Either SCons or CMake, depending on the project. Cross-compilation for ARM targets.
--- ---
## Compiler ## Compiler
| Compiler | Sprache | Qualifizierung | | Compiler | Language | Qualification |
|----------|---------|----------------| |-----------|----------|--------------------------------------------|
| GCC ARM | C/C++ | Eigene Qualifizierung nach ISO 26262 | | GCC ARM | C/C++ | Own qualification per ISO 26262 |
| Ferrocene | Rust | Zertifizierter Rust-Compiler fuer Safety | | Ferrocene | Rust | Certified Rust compiler for safety |
--- ---
## CI: Gitea Actions ## CI: Gitea Actions
Pipeline-Datei: `.gitea/workflows/validate.yml` Pipeline file: `.gitea/workflows/validate.yml`
Schritte bei jedem Push/PR: Steps on every push/PR:
1. Doorstop-Konsistenz pruefen 1. Doorstop consistency check
2. MISRA-Check 2. MISRA check
3. Unit Tests 3. Unit tests
4. Coverage 4. Coverage
5. Traceability-Report generieren 5. Traceability report generation
Syntax kompatibel mit GitHub Actions. Syntax compatible with GitHub Actions.
--- ---
## Open Source Analyse ## Open-source analysis
| Tool | Zweck | | Tool | Purpose |
|------|-------| |-----------|----------------------------------|
| ScanCode | Lizenz-Erkennung in Quellcode | | ScanCode | License detection in source code |
| FOSSology | Lizenz-Compliance-Analyse | | FOSSology | License compliance analysis |
Wichtig fuer Automotive: Lizenz-Compliance muss dokumentiert sein. Important for automotive: license compliance must be documented.
--- ---
## KI-Unterstuetzung: Continue.dev + Ollama ## AI assistance: Continue.dev + Ollama
Continue.dev als VS Code Extension mit Ollama als lokalem Backend. Continue.dev as a VS Code extension with Ollama as a local backend.
- Kein Cloud-Service, alle Daten bleiben lokal - No cloud service, all data stays local
- Kein Datenschutzproblem mit Kundendaten - No privacy issue with customer data
- Unterstuetzung beim Code-Schreiben, Reviews, Dokumentation - Assistance with code writing, reviews, documentation
--- ---
## Dokumentenexport: pandoc ## Document export: pandoc
```bash ```bash
pandoc dokument.md -o dokument.pdf --pdf-engine=xelatex pandoc document.md -o document.pdf --pdf-engine=xelatex
``` ```
Alle Dokumente in Markdown, Export nach PDF fuer Kunden und Audits. All documents in Markdown, export to PDF for customers and audits.
--- ---
## VS Code Extensions ## VS Code extensions
| Extension | Zweck | | Extension | Purpose |
|-----------|-------| |-----------------------------|--------------------------|
| PlantUML (jebbs.plantuml) | PlantUML-Preview | | PlantUML (jebbs.plantuml) | PlantUML preview |
| Markdown All in One | Markdown-Editing | | Markdown All in One | Markdown editing |
| GitLens | Git-History, Blame | | GitLens | Git history, blame |
| YAML (redhat.vscode-yaml) | YAML-Validierung | | YAML (redhat.vscode-yaml) | YAML validation |
| Continue.dev | KI mit Ollama | | Continue.dev | AI with Ollama |