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

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

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

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