dev-process/README.md

slohmaier Dev Process

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 project: slohmaier/demo-epb — Electric Parking Brake, applies this process end-to-end.

Core principle

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 strategy: hybrid

The two worlds — ISO-9001 audits vs day-to-day engineering — have different needs. We split cleanly:

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 templates are the source of truth; Word is built from them via pandoc (tools/generate_word_templates.sh).

Monorepo structure

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, ASIL-C+)
  docs/
    PID.md
    PM-Plan.md
    QA-Plan.md
    SWE-Plan.md
    Test-Plan.md
    reviews/
    non-conformities/
    traceability/       (generated by Doorstop)
  src/
  tests/
    unit/
    integration/
    results/
  misra/
    permits/
    records/
    reports/
  .gitea/
    workflows/validate.yml
  .doorstop.yml

Requirements with Doorstop (markdown mode)

Requirements are .md files with YAML frontmatter. PlantUML diagrams embed directly.

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

# SWE-001: CAN Bus Initialization

The CAN driver must initialize the bus with configurable baud rate.

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

Gitea renders this natively. VS Code with the PlantUML extension shows a live preview.

Doorstop verifies:
- All links resolve
- All requirements have tests
- No gaps in traceability

## Architecture design (ASPICE SYS.3 / SWE.2)

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 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** via `links:` in frontmatter:

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

# SWA-003: CAN Driver Component

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 → architecture via header comment:

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

Templates: templates/SA-template.md, templates/SWA-template.md.

Reviews

Every change — to code, requirements, documents, or plans — goes through a pull request.

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 = formal release. Git history is the audit trail.

Traceability

Four levels are linked:

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

Doorstop generates the matrix automatically:

doorstop publish all docs/traceability/

CI pipeline

Runs on every push and PR:

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

Files in this repo

Path	Content
toolstack/toolstack.md	Complete tool stack
gitea-aspice-setup.md	Setting up Gitea for ASPICE
dev-process-schaubild.html	V-model infographic
templates/	Markdown templates (source of truth)
templates-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_templates.sh	Builds the .docx versions from the .md templates via pandoc

Regenerate Word templates

# Rebuild master template + all derived Word templates
python3 tools/build_word_template.py
bash tools/generate_word_templates.sh

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

Using this process in your own projects

Three options:

1. Git submodule in your project:

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

2. Copy templates into the project and commit (static snapshot).
3. Fork / clone and use as the base for your own customisations.