Repo Blueprint¶

Eine Copier-Vorlage für GitHub-Repositories, die sich selbst pflegen: Tests bei jeder Änderung, ein Release-Bot, Sicherheitsprüfungen, ein Issue-Assistent und die Einstellungen des Repositorys als Code, für sieben Arten von Projekten, und ein Bot hält sie mit jeder neuen Version des Blueprints aktuell.

Ein Repository anlegen Zur Anleitung

Wie sich ein Repository selbst pflegt¶

Jede Änderung, deine oder die eines Bots, ist ein Pull Request, der merged, sobald alle Prüfungen grün sind, und der Release-Bot macht aus dem, was auf main ankommt, ein signiertes Release; drei Bots halten das Repository von selbst aktuell. In den Bildern ist Blau der Blueprint mit seinen Bots, Orange bist du mit allem, was dir gehört, und Grün ist das Ergebnis.

---
config:
  flowchart:
    wrappingWidth: 400
---
flowchart TB
    accTitle: Wie sich ein Repository selbst pflegt
    accDescr: copier copy legt aus dem Blueprint ein Repository an. Jede Änderung, deine oder die eines Bots, ist ein Pull Request, der merged, sobald alle Prüfungen grün sind, und der Release-Bot macht aus dem, was auf main ankommt, ein signiertes Release. Renovate, der Blueprint-Bot und der Settings-Bot halten das Repository von selbst aktuell.

    blueprint[("Repo Blueprint")]
    you(["Du"])
    renovate(["Renovate<br>alle 2 Stunden"])
    updater(["Blueprint-Bot<br>nach jedem Release<br>und jede Woche"])
    settings(["Settings-Bot<br>jede Woche"])

    subgraph repo ["Dein Repository"]
        pr["Pull Request"] --> checks{"Alle Prüfungen<br>grün?"}
        checks -- "ja" --> main["main"]
        main -- "Release-Bot" --> release["Signiertes Release"]
    end

    blueprint -- "copier copy" --> repo
    blueprint -. "ein neues Release" .-> updater
    you -- "eine Änderung" --> pr
    renovate -- "Updates" --> pr
    updater -- "copier update" --> pr
    settings -- "die Einstellungen als Code" --> repo

    classDef bot fill:#526cfe2e,stroke:#526cfe,stroke-width:2px
    classDef person fill:#f59e0b2e,stroke:#f59e0b,stroke-width:2px
    classDef done fill:#16a34a2e,stroke:#16a34a,stroke-width:2px
    class renovate,updater,settings bot
    class you person
    class release done

Was ein neues Repository bekommt¶

Prüfungen

scripts/check.sh bei jeder Änderung, lokal wie in der CI: Tests mit voller Abdeckung, in Python-Projekten auf jedem Kern, Typen, Lint und Paketbau. Dazu werden die Workflows, die Lizenz jeder Datei, das Markdown, der Sign-off jedes Commits und der Titel jedes Pull Requests geprüft. Ein vorübergehender Fehler eines Downloads lässt keinen Lauf scheitern: Jeder Download versucht es erneut.
PR-Coach

Jede Prüfung, die scheitert, sagt, was sie gefunden hat, warum das wichtig ist und wie man es behebt, mit den Befehlen dafür: in der Prüfung und in einem Kommentar am Pull Request, der jedem Push folgt, auch an einem Pull Request aus einem Fork. Was ein Befehl beheben kann, behebt der Pull Request selbst: Der Fix-Bot committet es, schlägt es an einem Fork vor und hält main repariert.
Sicherheit

CodeQL, OpenSSF Scorecard, Dependency Review, Secret Scan, SBOMs, die Sicherheitsprüfung der Workflows und jede Lock-Datei gegen die OSV-Datenbank. Jede Action ist auf einen Commit-Hash gepinnt.
Releases

Ein Pull Request mit der nächsten Version, bestimmt aus den Titeln der gemergten Pull Requests, und dem Changelog als Notes. Sein Merge veröffentlicht das Release mit Paket, SBOM und signierter Provenance (SLSA Build Level 3) und prüft es so, wie es seine Nutzer können.
Abhängigkeiten

Renovate, das der Blueprint alle zwei Stunden ausführt: Actions, Abhängigkeiten und Images eine Woche nach ihrem Release, sofort ein Update, das eine Schwachstelle behebt, oder den neuen Commit eines Branches, dem eine Action folgt. Routine-Updates mergen sich selbst, sobald alle Prüfungen grün sind; die wöchentliche Auffrischung jeder Lock-Datei wartet auf den Maintainer.
Issues

Der Issue-Assistent: eine erste Analyse jedes neuen Issues durch eine KI, die nur liest, Labels, Duplikate, Erinnerungen und das Schließen mit dem Release, das den Fix enthält. Jedes neue Release des Assistenten kommt von selbst in jedes Repository, sobald ein Bot geprüft hat, dass sein Release-Workflow es gebaut hat. Ein Bot, der auf main fehlschlägt, öffnet ein eigenes Issue, das sich schließt, sobald der Bot wieder besteht.
Website

Die Dokumentation aus docs/ als Website mit Suche und hellem und dunklem Design, auf Englisch und Deutsch. Jeder Pull Request baut sie streng, jede Änderung an main veröffentlicht sie auf GitHub Pages.
Diagramme

Jedes Diagramm als Bild, das alle sehen, auch in der GitHub-App und in den Stores, gezeichnet aus seiner Mermaid-Quelle; die Website zeichnet die Quelle live. Die Bots reparieren sie selbst: im Pull Request, auf main und nach einem Update des Renderers.
Einstellungen als Code

Merges, Rulesets, Sicherheit, Actions, Environments, Variablen, Labels und GitHub Pages in .github/repository.toml. Der Settings-Bot wendet sie nach jeder Änderung und jede Woche an.
Updates

Nach jedem Release und jede Woche prüft der Blueprint-Bot das Release, das unveränderlich und vom Release-Workflow des Blueprints signiert sein muss, führt dann copier update aus und hält einen Pull Request aktuell. Ohne Konflikte merged er sich selbst, sobald alle Prüfungen grün sind; die Dateien des Projekts und deine Commits auf seinem Branch werden nie überschrieben.
Community

README, Beitragsleitfaden, Verhaltenskodex, Sicherheitsrichtlinie und Sicherheitsdesign, Governance, Issue-Formulare, Aufzeichnungen der Entscheidungen und Discussions mit einer Ankündigung jedes Releases.
Coding-Agents

AGENTS.md gibt Claude Code, Codex, GitHub Copilot und Cursor die Befehle, die Regeln für Pull Requests und das Changelog, und welche Dateien dem Projekt gehören und welche dem Blueprint. Die Notizen des Projekts kommen aus .github/agents.project.md dazu.

Die Anleitung nennt jeden Bereich, auch den PR-Coach, die Abdeckung jedes Pull Requests, Mutationstests, wackelige Tests, abgebrochene Prüfungen, gescheiterte Releases, das Aufräumen und den Dev-Container.

Arten von Projekten¶

Home-Assistant-Integration

Ruff, mypy, Tests, HACS und hassfest; ein Zip-Asset für HACS.
Nextcloud-App

php-cs-fixer, Psalm mit seiner Taint-Analyse und PHPUnit mit jeder Zeile abgedeckt; ein signiertes Paket für den App Store.
GitHub Action

Eine Composite Action mit Ruff, mypy, Tests und einem Lauf der Action; Release-Tags und ein mitwandernder Major-Tag.
Python-Paket

Ruff, mypy, Tests und ein Build mit Hatchling; PyPI mit Trusted Publishing.
Node-Paket

TypeScript, tsc und node:test mit voller Abdeckung; npm mit Provenance.
Container-Image

Alpine per Digest, Hadolint, ein Build und ein Selbsttest; GHCR, Multi-Arch, mit SBOM und Provenance.

Ein Repository ohne Build prüft seine Textdateien und Shell-Skripte und macht nur Releases. Jede Art startet mit einem kleinen, funktionierenden Beispiel samt Tests, das durch den echten Code ersetzt wird. Die Anleitung nennt den Stack jeder Art.

Ein Repository anlegen¶

Copier ab 9.4, Git, die GitHub CLI und ein Checkout des Blueprints (für blueprint.py):

copier copy gh:Dennis-Otto/repo-blueprint mein-projekt
cd mein-projekt
git init && git add --all && git commit --signoff --message "chore: start from the blueprint"
gh repo create Dennis-Otto/mein-projekt --public --source . --push
python3 ../repo-blueprint/blueprint.py settings apply
python3 ../repo-blueprint/blueprint.py checklist

Copier fragt nach Name, einer Beschreibung in einem Satz, der Art des Projekts, der Lizenz (MIT, MIT-0, BSD-3-Clause, Apache-2.0, GPL-3.0-or-later oder AGPL-3.0-or-later) und ein paar Details der Art. settings apply setzt alles, was die API setzen kann; checklist zeigt, was noch eine Person erledigen muss, etwa die Secrets, und welche Schritte schon erledigt sind.

Die Anleitung beschreibt, was jedes Repository einmal braucht, etwa die Release-App, und wie ein bestehendes Repository den Blueprint übernimmt.

Mehr erfahren¶

Anleitung

Alles, was ein neues Repository bekommt, die Einstellungen als Code, die Updates und was einem Projekt gehört.

Zur Anleitung
Roadmap

Wohin sich der Blueprint in den nächsten zwölf Monaten entwickelt und was er nicht tun wird, auf Englisch.

Roadmap
Sicherheitsdesign

Was der Blueprint schützt, wem er vertraut, die Bedrohungen mit ihren Gegenmaßnahmen und die verbleibenden Risiken, auf Englisch.

Sicherheitsdesign
Entscheidungen

Die Entscheidungen, die den Blueprint prägen, jede mit ihren Gründen, auf Englisch.

Entscheidungen
Releases und Änderungen

Jedes Release mit seinen Notes auf GitHub und die Änderungen jeder Version, auf Englisch.

Releases · Änderungen
Dashboard

Jedes öffentliche Repository des Besitzers auf einen Blick: das Release des Blueprints, auf dem es steht, seine Releases, Pull Requests, Workflow-Läufe, Scorecard und Gesundheit.

Dashboard