Contributing to Prometheus

Erstmal: Danke. Prometheus lebt davon, dass Maintainer von OSS-Libraries, Mirror-Betreiber, Forschende und Tooling-Entwickler:innen mitarbeiten.

Dieses Dokument deckt drei Pfade:

1. Code-Beitrag (PR gegen main)
2. Mirror-Betrieb (eigene Mirror-Instanz spiegeln in mirrors.json im prometheus-federation-Repo)
3. Maintainer-Erweiterung (MAINTAINERS.md ergänzen)

Vorher: lies CODE_OF_CONDUCT.md. Sicherheitslücken nicht hier melden, sondern via SECURITY.md.

1. Code-Beitrag#

Setup#

Voraussetzungen: Node 20+, Python 3.10+, Git, make (optional, nur wenn du den globalen Test-Runner über Make abgebildet sehen willst).

git clone https://codeberg.org/mortisnexus/prometheus-project.git
cd prometheus-project

# proto-Workspace (Submission-Schema + Crypto)
cd src/proto/crypto-py && python -m venv .venv && . .venv/bin/activate && pip install -e .[test]
cd ../crypto-ts && npm install
cd ../../..

# Konzept-Doku rendern (lokal)
# `--directory` ist Pflicht, nicht `--bind`: Ohne die Einschränkung läge unter
# dem servierten Root auch .secure/ (private ed25519-Keys, Mirror-DIDs) und
# PEN/_findings/. `--bind 127.0.0.1` entfernt davon nur die NETZ-Exposition —
# jeder lokale Prozess erreicht 127.0.0.1 weiterhin, etwa ein postinstall-Hook
# in einem parallel laufenden `npm install`, der GET /.secure/ ausliest.
python3 -m http.server 8000 --bind 127.0.0.1 --directory concept   # → http://localhost:8000/

Coding-Standards#

Pro Workspace gilt:

• Python: ruff check, ruff format --check, mypy --strict müssen grün sein. Tests: pytest -q. Coverage-Schwelle ≥ 80 % auf neuem Code.
• TypeScript: npm run typecheck (= tsc --noEmit), npm test (= vitest run). Coverage-Schwelle ≥ 80 % (V8-Provider).
• Rust (ab src/mirror/): cargo fmt --check, cargo clippy -- -D warnings, cargo test.

CI verdrahtet das in .forgejo/workflows/pr-quick.yml (Codeberg) und spiegelt nach .github/workflows/pr-quick.yml für GitHub-Mirror. ADR-DEV-0001 dokumentiert die CI-Wahl.

4-Agent-Review-Gate#

Vor jedem Commit/Push muss ./review.sh ein PASS aller vier Review-Agents (Gauss, Euler, Bohr, Newton) zeigen — siehe CLAUDE.md §Code Review Process. Das schließt explizit ein:

• Konsistenz gegen concept/ (kein Drift zwischen Code und Doku ohne PR-Ergänzung der Doku).
• PII-Defense-in-Depth darf nicht „aufgeräumt" werden — Stufen 5 + 6 aus concept/data-flow.md müssen koexistieren.

PR-Workflow#

1. Branch von main: feature/<sprint-id>-<kurzname> oder fix/<thema> oder doc/<thema>.
2. Vor dem ersten Commit: pre-commit install (siehe .pre-commit-config.yaml).
3. Commit-Message: imperativ, Deutsch ok, eine Zeile <72 Zeichen + leere Zeile + Body. Konsole/CHANGELOG-Sätze in Vergangenheit/Perfekt formulieren. Sprint-ID in der ersten Zeile als sprint(<id>): … wenn der PR genau einen Sprint adressiert.
4. Tests grün, Coverage nicht gesenkt.
5. PR-Body verlinkt: Sprint, K-Bezug (falls gemessen), berührte ADRs.
6. Mindestens ein Maintainer-Review approve; Federation-relevante Änderungen (concept/ADR-v2-*, mirrors.json-Schema-Edits, neue Major-Schema-Version) brauchen zwei Maintainer.

2. Mirror-Betrieb#

Ein Mirror akzeptiert Submissions (POST /v1/submit), persistiert in ClickHouse, hängt Hashes an Sigstore Rekor und veröffentlicht tägliche Open-Data-Snapshots (concept/system-overview.md §4–6).

Voraussetzungen, bevor du mirrors.json ergänzt (ADR-v2-0006):

1. Eine Mirror-DID (did:key:z…) erzeugt und sicher verwahrt.
2. EU-Hosting bevorzugt (DSGVO-Pragmatik); andere Regionen erlaubt, GDPR-Verantwortung liegt dann beim Betreiber (infrastructure-map.md §4.5).
3. Datenschutzerklärung auf Basis des Templates in infra/legal/mirror-agb-template.md öffentlich publiziert; URL als privacy_policy_url im Mirror-Record (Pflichtfeld, siehe ADR-v2-0006 Schema).
4. Mindestens drei Co-Sign-Reviews auf deinen mirrors.json-PR.

infra/docker-compose.yml startet den Phase-1-Mirror-Stack lokal — ClickHouse + Sigstore-Rekor + Mock-Mirror-API. Für Produktion siehe src/mirror/README.md (kommt mit Sprint P2-Ph1-S1).

3. Maintainer-Erweiterung#

Pfad in MAINTAINERS.md dokumentiert. Kurz:

1. PR gegen MAINTAINERS.md mit deiner DID, Handle, Organisation, Rollen-Wunsch.
2. Zwei bestehende Maintainer co-signieren.
3. Innerhalb von 14 Tagen ein erfolgreicher Co-Sign auf das nächste Federation-Artefakt.

Schreibstil & Sprache#

• Konzept-Doku unter concept/ ist Deutsch, sachlich, beratend. Englisch nur für Standardbegriffe (PURL, Mirror, SDK, Federation, Snapshot, k-Anon).
• Code und Code-Kommentare sind Englisch (npm/PyPI/Crates erwarten EN-Dokumentation).
• Commits, Issues, PRs dürfen Deutsch oder Englisch sein — Hauptsache klar.

Frontmatter-Pflicht in concept/*.md:

---
title: …
status: …
audience: …
---

Bei substantieller Änderung status:-Zeile updaten. Konsistenz-Wächter ist concept/06-offene-punkte.md und concept/06b-doku-audit.md.

Wo melde ich was?#