From 54e7decd9c1e830b719365150b56dc34db3d4746 Mon Sep 17 00:00:00 2001 From: Stefan Lohmaier Date: Tue, 12 May 2026 03:43:36 -0700 Subject: [PATCH] feat(i18n): toolstack.md + gitea-aspice-setup.md in English 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. --- gitea-aspice-setup.md | 154 +++++++++++++++--------------- toolstack/toolstack.md | 208 ++++++++++++++++++++--------------------- 2 files changed, 181 insertions(+), 181 deletions(-) diff --git a/gitea-aspice-setup.md b/gitea-aspice-setup.md index d759910..07cea9a 100644 --- a/gitea-aspice-setup.md +++ b/gitea-aspice-setup.md @@ -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 # docker-compose.yml @@ -26,7 +26,7 @@ services: docker compose up -d ``` -### PlantUML-Rendering aktivieren +### Enable PlantUML rendering In `data/gitea/conf/app.ini`: @@ -39,7 +39,7 @@ RENDER_COMMAND = plantuml -tsvg -pipe IS_INPUT_FILE = false ``` -Oder über den öffentlichen Renderer (kein lokales PlantUML nötig): +Or via the public renderer (no local PlantUML needed): ```ini [server] @@ -51,85 +51,85 @@ NEED_POSTPROCESS = true RENDER_COMMAND = curl -s https://www.plantuml.com/plantuml/svg/~h ``` -## Organisations- und Repo-Struktur +## Organisation and repo structure ``` -Organisation: slohmaier (eigene Projekte) -Organisation: kunde-projektname (Kundenprojekte) - Repo: projektname (Monorepo: reqs + docs + src + tests) +Organisation: slohmaier (own projects) +Organisation: client-projectname (customer projects) + 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 | -|-------|-------|------------| -| `type:requirement` | blau | Anforderungs-Issue | -| `type:architecture` | dunkelblau | Architektur-Entscheidung | -| `type:implementation` | grün | Implementierungsaufgabe | -| `type:test` | hellgrün | Testfall | -| `type:document` | grau | Dokument-Änderung | -| `aspice:NC` | rot | Non-Conformity | -| `aspice:change-request` | orange | Change Request | -| `aspice:finding` | gelb | QA-Finding | -| `status:review-required` | lila | Wartet auf Review | -| `status:approved` | grün | Freigegeben | -| `severity:critical` | dunkelrot | Kritisch | -| `severity:major` | orange | Schwerwiegend | -| `severity:minor` | gelb | Geringfügig | +| Label | Colour | Use | +|-------|--------|-----| +| `type:requirement` | blue | Requirement issue | +| `type:architecture` | dark blue | Architecture decision | +| `type:implementation` | green | Implementation task | +| `type:test` | light green | Test case | +| `type:document` | grey | Document change | +| `aspice:NC` | red | Non-conformity | +| `aspice:change-request` | orange | Change request | +| `aspice:finding` | yellow | QA finding | +| `status:review-required` | purple | Waiting for review | +| `status:approved` | green | Approved | +| `severity:critical` | dark red | Critical | +| `severity:major` | orange | Major | +| `severity:minor` | yellow | Minor | -## Branch-Schutz +## Branch protection -Für `main`: -- Kein direktes Pushen -- Mind. 1 Approval erforderlich -- CI muss grün sein +For `main`: +- No direct pushing +- At least 1 approval required +- 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 -develop Integrationsbranch -feature/SWE-001-can-init Feature mit Req-Referenz -docs/qa-plan-v1 Dokument-Änderung -fix/NC-003-misra-violation Bugfix mit NC-Referenz -release/v1.0 Release-Branch +main protected, stable, only via PR +develop integration branch +feature/SWE-001-can-init feature with requirement reference +docs/qa-plan-v1 document change +fix/NC-003-misra-violation bug fix with NC reference +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 -2. Datei anlegen: reqs/swe/SWE-001.md -3. PR erstellen mit Titel: "[REQ] SWE-001: CAN Bus Initialisierung" -4. Reviewer zuweisen -5. Nach Approval → Merge +2. Create file: reqs/swe/SWE-001.md +3. Create PR titled: "[REQ] SWE-001: CAN Bus Initialization" +4. Assign reviewer +5. After approval → merge ``` -### Dokument ändern +### Change a document ``` 1. Branch: docs/qa-plan-update -2. Änderung in docs/QA-Plan.md -3. PR mit Beschreibung der Änderung -4. Reviewer zuweisen → Approval → Merge +2. Change in docs/QA-Plan.md +3. PR with description of the change +4. Assign reviewer → approval → merge ``` -### Code-Änderung +### Code change ``` 1. Branch: feature/SWE-001-can-init -2. Commit-Message: "feat(SWE-001): implement CAN bus init at configurable baudrate" -3. PR: "Refs #" -4. CI muss grün sein -5. Reviewer → Approval → Merge +2. Commit message: "feat(SWE-001): implement CAN bus init at configurable baudrate" +3. PR: "Refs #" +4. CI must be green +5. Reviewer → approval → merge ``` -## Commit-Message-Konvention +## Commit-message convention ``` 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 ``` -Format: `(): ` +Format: `(): ` -## Gitea Actions — Basis-Pipeline +## Gitea Actions — basic pipeline ```yaml # .gitea/workflows/validate.yml @@ -183,9 +183,9 @@ jobs: git push ``` -## Doorstop konfigurieren +## Configure Doorstop -`.doorstop.yml` im Repo-Root: +`.doorstop.yml` at the repo root: ```yaml settings: @@ -193,7 +193,7 @@ settings: prefix: REQ ``` -`.doorstop` in jedem Requirements-Unterordner: +`.doorstop` in each requirements subfolder: ```yaml # reqs/sys/.doorstop @@ -219,24 +219,24 @@ settings: parent: SWE ``` -## VS Code Extensions für diesen Stack +## VS Code extensions for this stack -| Extension | ID | Zweck | -|-----------|-----|-------| -| PlantUML | jnbt.plantuml | Diagramm-Preview in Markdown | -| Markdown All in One | yzhang.markdown-all-in-one | Markdown-Bearbeitung | -| YAML | redhat.vscode-yaml | YAML-Frontmatter in .md | -| GitLens | eamodio.gitlens | Git-History und Blame | -| Continue | Continue.continue | KI-Assistent lokal via Ollama | +| Extension | ID | Purpose | +|--------------------|------------------------------|-------------------------------| +| PlantUML | jnbt.plantuml | Diagram preview in Markdown | +| Markdown All in One| yzhang.markdown-all-in-one | Markdown editing | +| YAML | redhat.vscode-yaml | YAML frontmatter in .md | +| GitLens | eamodio.gitlens | Git history and blame | +| Continue | Continue.continue | AI assistant, local via Ollama| -## Traceability-Übersicht +## Traceability overview ``` -SYS-001 (System-Anforderung) - └── SWE-001 (Software-Anforderung) [links: SYS-001] - └── TST-001 (Testfall) [links: SWE-001] - └── Commit abc1234 [feat(SWE-001): ...] - └── PR #12 [Refs #5 (Issue: SWE-001)] +SYS-001 (system requirement) + └── SWE-001 (software requirement) [links: SYS-001] + └── TST-001 (test case) [links: SWE-001] + └── commit abc1234 [feat(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. diff --git a/toolstack/toolstack.md b/toolstack/toolstack.md index 8d15a1a..f867ddf 100644 --- a/toolstack/toolstack.md +++ b/toolstack/toolstack.md @@ -1,57 +1,57 @@ # 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 | -|-----------|------|-----------| -| Source Control | Gitea (self-hosted) | `tea` CLI fuer Kommandozeile, VS Code Integration | -| Requirements | Doorstop (Markdown-Modus) | Requirements als `.md` mit PlantUML eingebettet | -| Architektur-Design | Doorstop + PlantUML | SA / SWA / SWD als `.md` mit Mapping per `links:` (ASPICE SYS.3 / SWE.2 / SWE.3) | -| Diagramme | PlantUML | Eingebettet in Markdown, gerendert von Gitea und VS Code | -| MISRA | Cppcheck + MISRA-Addon | Kostenlos, Deviation Permits/Records via Doorstop | -| Coverage | gcov/lcov | Bis ASIL-B; MCDC-Star fuer ASIL-C/D | -| Unit Tests | CppUTest oder Google Test | Je nach Projekt | -| Static Analysis | Cppcheck, clang-tidy | Cppcheck auch fuer MISRA | -| Build | SCons, CMake | Je nach Projekt | -| Compiler | GCC ARM | Eigene Qualifizierung; Ferrocene fuer Rust | -| CI | Gitea Actions | Pipeline im Monorepo unter `.gitea/workflows/` | -| Open Source Analyse | ScanCode, FOSSology | Lizenz-Compliance | -| KI-Unterstuetzung | Continue.dev + Ollama | VS Code Extension, lokal, kein Cloud-Datenschutzproblem | -| Dokumentenexport | pandoc | Markdown nach PDF | -| Editor | VS Code | Primaerer Editor fuer alles | +| Category | Tool | Notes | +|-----------|------|-------| +| Source Control | Gitea (self-hosted) | `tea` CLI for command line, VS Code integration | +| Requirements | Doorstop (Markdown mode) | Requirements as `.md` with embedded PlantUML | +| Architecture design | Doorstop + PlantUML | SA / SWA / SWD as `.md` with mapping via `links:` (ASPICE SYS.3 / SWE.2 / SWE.3) | +| Diagrams | PlantUML | Embedded in Markdown, rendered by Gitea and VS Code | +| MISRA | Cppcheck + MISRA addon | Free, deviation permits/records via Doorstop | +| Coverage | gcov/lcov | Up to ASIL-B; MCDC-Star for ASIL-C/D | +| Unit tests | CppUTest or Google Test | Project-dependent | +| Static analysis | Cppcheck, clang-tidy | Cppcheck also for MISRA | +| Build | SCons, CMake | Project-dependent | +| Compiler | GCC ARM | Own qualification; Ferrocene for Rust | +| CI | Gitea Actions | Pipeline in the monorepo under `.gitea/workflows/` | +| Open-source analysis | ScanCode, FOSSology | License compliance | +| AI assistance | Continue.dev + Ollama | VS Code extension, local, no cloud privacy issue | +| Document export | pandoc | Markdown to PDF | +| Editor | VS Code | Primary editor for everything | --- ## 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 -- Gitea Actions fuer CI/CD (kompatibel mit GitHub Actions Syntax) -- PlantUML-Rendering in Markdown (per PlantUML-Server) -- `tea` CLI fuer Kommandozeilen-Workflows -- Branch Protection und Approval-Workflows +- Web UI for PRs, reviews, issues +- Gitea Actions for CI/CD (compatible with GitHub Actions syntax) +- PlantUML rendering in Markdown (via PlantUML server) +- `tea` CLI for command-line 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:** -- Requirements sind Markdown, versioniert in Git -- PlantUML-Diagramme direkt im Requirement eingebettet -- Traceability-Pruefung per CLI: `doorstop check` -- Report-Generierung: `doorstop publish all docs/traceability/` -- Gitea rendert alles direkt (Markdown + PlantUML) +**Advantages:** +- Requirements are Markdown, versioned in Git +- PlantUML diagrams embedded directly in the requirement +- Traceability check via CLI: `doorstop check` +- Report generation: `doorstop publish all docs/traceability/` +- Gitea renders everything natively (Markdown + PlantUML) -**Requirement-Format:** +**Requirement format:** ```markdown --- @@ -61,162 +61,162 @@ links: - 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/` | | SWA | Software Architectural Design | SWE.2 | `arch/swe/` | | 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 -doorstop check # bidirektional, schlaegt fehl bei Luecken -doorstop publish all docs/traceability/ # Traceability-Matrix erzeugen +doorstop check # bidirectional, fails on gaps +doorstop publish all docs/traceability/ # generate traceability matrix ``` -Vorlagen unter `dev-process/vorlagen/`: +Templates under `dev-process/vorlagen/`: - `SA-vorlage.md` — System 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:** -- Gitea: Automatisch via PlantUML-Server (Konfiguration in `app.ini`) -- VS Code: PlantUML-Extension (jebbs.plantuml) fuer Live-Preview -- Export: pandoc mit PlantUML-Filter fuer PDF +- Gitea: automatically via the PlantUML server (configuration in `app.ini`) +- VS Code: PlantUML extension (jebbs.plantuml) for live preview +- 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 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 -| ASIL | Tool | Methode | -|------|------|---------| -| A–B | gcov/lcov | Statement + Branch Coverage | -| C–D | MCDC-Star | MC/DC Coverage | +| ASIL | Tool | Method | +|------|-----------|-------------------------------| +| A–B | gcov/lcov | Statement + branch 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/` -- Ergebnisse unter `tests/results/` -- CI fuehrt Tests bei jedem Push aus +- Tests under `tests/unit/` +- Results under `tests/results/` +- CI runs tests on every push --- -## Static Analysis +## Static analysis -| Tool | Zweck | -|------|-------| -| Cppcheck | Allgemeine statische Analyse + MISRA | -| clang-tidy | Modernisierung, Stil, Bugs | +| Tool | Purpose | +|------------|----------------------------------------| +| Cppcheck | General static analysis + MISRA | +| clang-tidy | Modernisation, style, bugs | -Beide laufen in der CI-Pipeline. +Both run in the CI pipeline. --- ## 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 | Sprache | Qualifizierung | -|----------|---------|----------------| -| GCC ARM | C/C++ | Eigene Qualifizierung nach ISO 26262 | -| Ferrocene | Rust | Zertifizierter Rust-Compiler fuer Safety | +| Compiler | Language | Qualification | +|-----------|----------|--------------------------------------------| +| GCC ARM | C/C++ | Own qualification per ISO 26262 | +| Ferrocene | Rust | Certified Rust compiler for safety | --- ## CI: Gitea Actions -Pipeline-Datei: `.gitea/workflows/validate.yml` +Pipeline file: `.gitea/workflows/validate.yml` -Schritte bei jedem Push/PR: -1. Doorstop-Konsistenz pruefen -2. MISRA-Check -3. Unit Tests +Steps on every push/PR: +1. Doorstop consistency check +2. MISRA check +3. Unit tests 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 | -|------|-------| -| ScanCode | Lizenz-Erkennung in Quellcode | -| FOSSology | Lizenz-Compliance-Analyse | +| Tool | Purpose | +|-----------|----------------------------------| +| ScanCode | License detection in source code | +| 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 -- Kein Datenschutzproblem mit Kundendaten -- Unterstuetzung beim Code-Schreiben, Reviews, Dokumentation +- No cloud service, all data stays local +- No privacy issue with customer data +- Assistance with code writing, reviews, documentation --- -## Dokumentenexport: pandoc +## Document export: pandoc ```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 | -|-----------|-------| -| PlantUML (jebbs.plantuml) | PlantUML-Preview | -| Markdown All in One | Markdown-Editing | -| GitLens | Git-History, Blame | -| YAML (redhat.vscode-yaml) | YAML-Validierung | -| Continue.dev | KI mit Ollama | +| Extension | Purpose | +|-----------------------------|--------------------------| +| PlantUML (jebbs.plantuml) | PlantUML preview | +| Markdown All in One | Markdown editing | +| GitLens | Git history, blame | +| YAML (redhat.vscode-yaml) | YAML validation | +| Continue.dev | AI with Ollama |