dev-process/gitea-aspice-setup.md

# Setting up Gitea for ASPICE 4.0

Concrete setup guide for the slohmaier Dev Process on top of Gitea, Doorstop, and Gitea Actions.

## Install Gitea

### Docker (recommended)

```yaml
# docker-compose.yml
version: "3"
services:
  gitea:
    image: gitea/gitea:latest
    ports:
      - "3000:3000"
      - "222:22"
    volumes:
      - ./data:/data
    environment:
      - USER_UID=1000
      - USER_GID=1000
```

```bash
docker compose up -d
```

### Enable PlantUML rendering

In `data/gitea/conf/app.ini`:

```ini
[markup.plantuml]
ENABLED         = true
NEED_POSTPROCESS= true
FILE_EXTENSIONS = .puml
RENDER_COMMAND  = plantuml -tsvg -pipe
IS_INPUT_FILE   = false
```

Or via the public renderer (no local PlantUML needed):

```ini
[server]
OFFLINE_MODE = false

[markup.plantuml]
ENABLED = true
NEED_POSTPROCESS = true
RENDER_COMMAND   = curl -s https://www.plantuml.com/plantuml/svg/~h
```

## Organisation and repo structure

```
Organisation: slohmaier          (own projects)
Organisation: client-projectname  (customer projects)
  Repo: projectname              (monorepo: reqs + docs + src + tests)
```

One repo per project. Do not split into many repos.

## Label scheme

Create all labels at the organisation level, then they are available in every repo.

| 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 protection

For `main`:
- No direct pushing
- At least 1 approval required
- CI must be green

Configurable under: Repo → Settings → Branches → Branch Protection

## Branching strategy

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

### Create a new requirement
```
1. Branch: reqs/SWE-001-can-init
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
```

### Change a document
```
1. Branch: docs/qa-plan-update
2. Change in docs/QA-Plan.md
3. PR with description of the change
4. Assign reviewer → approval → merge
```

### 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 #<issue-number>"
4. CI must be green
5. Reviewer → approval → merge
```

## Commit-message convention

```
feat(SWE-001): implement CAN bus initialization
fix(NC-003): resolve MISRA Rule 14.4 violation
docs(QA-Plan): add review schedule for SWE phase
test(SWE-001): add unit test for CAN init error handling
```

Format: `<type>(<id>): <description>`

## Gitea Actions — basic pipeline

```yaml
# .gitea/workflows/validate.yml
name: Validate
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install tools
        run: |
          pip install doorstop
          apt-get install -y cppcheck

      - name: Doorstop check
        run: doorstop check

      - name: MISRA check
        run: |
          cppcheck --addon=misra --error-exitcode=1 \
                   --suppress=misra-c2012-15.5 \
                   src/

      - name: Unit tests
        run: make test

      - name: Coverage
        run: make coverage

      - name: Publish traceability
        run: |
          doorstop publish all docs/traceability/
          git config user.email "ci@slohmaier.com"
          git config user.name "CI"
          git add docs/traceability/
          git diff --cached --quiet || git commit -m "ci: update traceability report"
          git push
```

## Configure Doorstop

`.doorstop.yml` at the repo root:

```yaml
settings:
  digits: 3
  prefix: REQ
```

`.doorstop` in each requirements subfolder:

```yaml
# reqs/sys/.doorstop
settings:
  digits: 3
  prefix: SYS
  parent: null
```

```yaml
# reqs/swe/.doorstop
settings:
  digits: 3
  prefix: SWE
  parent: SYS
```

```yaml
# tests/unit/.doorstop
settings:
  digits: 3
  prefix: TST
  parent: SWE
```

## VS Code extensions for this stack

| 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 overview

```
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 verifies the complete chain automatically on every CI run.