Contributing to Prometheus

First of all: thank you. Prometheus lives on the participation of OSS library maintainers, mirror operators, researchers and tooling developers.

This document covers three paths:

1. Code contribution (a PR against main)
2. Running a mirror (registering your own mirror instance in mirrors.json in the prometheus-federation repository)
3. Becoming a maintainer (adding yourself to MAINTAINERS.md)

Before you start: read CODE_OF_CONDUCT.md. Do not report security vulnerabilities here — use the path in SECURITY.md.

1. Code contribution#

Setup#

Prerequisites: Node 20+, Python 3.10+, Git, make (optional, only if you want the global test runner exposed through Make).

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 ../../..

# Render the concept documentation (locally)
# `--directory` is what protects you, not `--bind`: without that restriction
# the served root would also contain .secure/ (private ed25519 keys, mirror
# DIDs) and PEN/_findings/. `--bind 127.0.0.1` removes only the NETWORK
# exposure — every local process still reaches 127.0.0.1, for instance a
# postinstall hook in a parallel `npm install` reading GET /.secure/.
python3 -m http.server 8000 --bind 127.0.0.1 --directory concept   # → http://localhost:8000/

Coding standards#

Per workspace:

• Python: ruff check, ruff format --check, mypy --strict must be green. Tests: pytest -q. Coverage threshold ≥ 80 % on new code.
• TypeScript: npm run typecheck (= tsc --noEmit), npm test (= vitest run). Coverage threshold ≥ 80 % (V8 provider).
• Rust (from src/mirror/ onwards): cargo fmt --check, cargo clippy -- -D warnings, cargo test.

CI wires this up in .forgejo/workflows/pr-quick.yml (Codeberg) and mirrors it to .github/workflows/pr-quick.yml for the GitHub mirror. ADR-DEV-0001 documents the CI choice.

The 4-agent review gate#

Before every commit or push, ./review.sh must show a PASS from all four review agents (Gauss, Euler, Bohr, Newton) — see CLAUDE.md § Code Review Process. That explicitly includes:

• Consistency against concept/ (no drift between code and documentation without the PR also updating the documentation).
• PII defense in depth must not be "tidied up" — stages 5 and 6 from concept/data-flow.md have to coexist.

PR workflow#

1. Branch from main: feature/<sprint-id>-<short-name> or fix/<topic> or doc/<topic>.
2. Before the first commit: pre-commit install (see .pre-commit-config.yaml).
3. Commit message: imperative, German is fine, one line under 72 characters + a blank line + a body. Console and CHANGELOG sentences are written in the past tense. Put the sprint ID on the first line as sprint(<id>): … if the PR addresses exactly one sprint.
4. Tests green, coverage not lowered.
5. The PR body links: the sprint, the K reference (if measured), the ADRs touched.
6. At least one maintainer review approval; federation-relevant changes (concept/ADR-v2-*, mirrors.json schema edits, a new major schema version) need two maintainers.

2. Running a mirror#

A mirror accepts submissions (POST /v1/submit), persists them in ClickHouse, appends hashes to Sigstore Rekor and publishes daily Open Data snapshots (concept/system-overview.md §4–6).

Prerequisites before you add yourself to mirrors.json (ADR-v2-0006):

1. A mirror DID (did:key:z…) generated and kept safe.
2. EU hosting preferred (GDPR pragmatism); other regions are permitted, in which case GDPR responsibility sits with the operator (infrastructure-map.md §4.5).
3. A privacy policy based on the template in infra/legal/mirror-agb-template.md published publicly; its URL goes into the mirror record as privacy_policy_url (a mandatory field, see the ADR-v2-0006 schema).
4. At least three co-sign reviews on your mirrors.json PR.

infra/docker-compose.yml starts the phase-1 mirror stack locally — ClickHouse + Sigstore Rekor + a mock mirror API. For production see src/mirror/README.md (arrives with sprint P2-Ph1-S1).

3. Becoming a maintainer#

The path is documented in MAINTAINERS.md. In short:

1. A PR against MAINTAINERS.md with your DID, handle, organisation and the role you are asking for.
2. Two existing maintainers co-sign.
3. Within 14 days, one successful co-sign on the next federation artefact.

Writing style & language#

• The concept documentation under concept/ is German, factual, advisory. English only for standard terms (PURL, mirror, SDK, federation, snapshot, k-anon).
• Code and code comments are English (npm/PyPI/crates expect English documentation).
• Commits, issues, PRs may be German or English — as long as they are clear.

Front matter is mandatory in concept/*.md:

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

Update the status: line on any substantial change. The consistency watchdogs are concept/06-offene-punkte.md and concept/06b-doku-audit.md.

Where do I report what?#