Repo Blueprint im Vergleich mit Template-Repositorys, Cookiecutter, Copier-Vorlagen und projen¶

Jedes Werkzeug auf dieser Seite macht aus einer Vorlage ein neues Repository. Sie unterscheiden sich darin, was nach dem Kopieren geschieht: ob Verbesserungen der Vorlage das Repository später erreichen, ob Code der Vorlage auf deinem Rechner läuft und wie viel vom Repository über seine Dateien hinaus sie pflegen. Diese Seite sagt, wo der Blueprint vorne liegt und wo ein anderes Werkzeug besser passt.

Die Werkzeuge: Template-Repositorys von GitHub, Cookiecutter mit cruft, andere Vorlagen für Copier, etwa copier-uv und scientific-python/cookie, und projen.

Wo der Blueprint vorne liegt¶

Ein getestetes Ausrollen in jedes Repository. Bevor eine Änderung der Vorlage merged, macht der Workflow Variants daraus ein neues Repository jeder Art und aktualisiert eines jeder Art von der neuesten Version, und der Workflow Downstream aktualisiert damit einen Klon jedes echten Repositorys. Nach dem Release startet der Workflow Rollout den Blueprint-Bot jedes Repositorys, eines nach dem anderen; der Bot prüft das signierte Release, führt copier update aus und hält einen Pull Request, der merged, sobald alle Prüfungen grün sind.
Beim Kopieren läuft kein Code der Vorlage. Die Vorlage hat keine Tasks, Migrationen oder Jinja-Erweiterungen, also braucht Copier kein --trust, weder beim Kopieren noch bei einem Update.
Einstellungen als Code, mit einem Bot gegen Abweichungen. Die Rulesets, die Sicherheit, Actions, die Environments, die Variablen, die Labels und GitHub Pages stehen in .github/repository.toml, und der Einstellungs-Bot wendet sie nach jeder Änderung und jede Woche an.
Releases nach SLSA Build Level 3, mit SBOMs und VEX. Ein Release hat signierte Tags, die Provenance eines isolierten Builds, SBOMs als SPDX und CycloneDX, ein OpenVEX-Dokument und ein unveränderliches Release, und sein Workflow prüft es so, wie seine Nutzer es können, auch jede Woche.
Home Assistant, Nextcloud und GitHub Actions in einem Standard, neben Python- und Node-Paketen, Containern und Repositories ohne Build: dieselben Prüfungen, Bots und Einstellungen für jede Art, mit den Werkzeugen jeder Art.

---
config:
  flowchart:
    wrappingWidth: 400
---
flowchart TB
    accTitle: Wie eine Änderung der Vorlage die Repositories vor ihrem Release trifft
    accDescr: Ein Pull Request ändert, was die Repositories vom Blueprint bekommen. Der Variants-Workflow erzeugt ein neues Repository jeder Art, bringt eines jeder Art vom letzten Release auf den Stand und eines mit den Antworten jedes Repositorys aus tests/answers, das jede Datei so bekommen muss wie ein neues Repository mit diesen Antworten und den Bau seiner Website und den Lint seiner Workflows und seines Markdowns bestehen muss. Der Downstream-Workflow klont jedes Repository und aktualisiert es wie sein Blueprint-Bot, auf main und auf den Pull Request, und nennt die Dateien, deren Update der Pull Request ändert, und jeden Konflikt; ein Konflikt, den der Pull Request in einen Workflow oder ein Skript bringt, lässt ihn scheitern. Dann wird der Pull Request gemergt, und das Release und der Rollout bringen ihn in jedes Repository.

    change(["Ein Pull Request ändert die Vorlage"])
    variants["Variants: ein neues Repository jeder Art,<br>eines vom letzten Release aktualisiert<br>und eines mit den Antworten jedes Repositorys<br>aus tests/answers/"]
    downstream["Downstream: jedes Repository geklont<br>und wie von seinem Blueprint-Bot aktualisiert,<br>auf main und auf den Pull Request"]
    summary["Die Zusammenfassung: die Dateien, deren Update<br>der Pull Request ändert, und jeder Konflikt"]
    conflict{"Ein Konflikt, den der Pull Request<br>in einen Workflow oder ein Skript bringt?"}
    fix(["Die Vorlage korrigieren oder im Changelog sagen,<br>wie ein Repository ihn löst"])
    merge["Der Pull Request wird gemergt"]
    rollout(["Das Release und der Rollout bringen ihn<br>in jedes Repository"])

    change --> variants & downstream
    downstream --> summary --> conflict
    conflict -- "ja: die Prüfung scheitert" --> fix --> change
    conflict -- "nein" --> merge
    variants -- "jede Variante besteht" --> merge
    merge --> rollout

    classDef bot fill:#526cfe2e,stroke:#526cfe,stroke-width:2px
    classDef person fill:#f59e0b2e,stroke:#f59e0b,stroke-width:2px
    classDef result fill:#16a34a2e,stroke:#16a34a,stroke-width:2px
    class variants,downstream,summary bot
    class change,fix person
    class rollout result

Punkt für Punkt¶

Ein Strich heißt, dass das Werkzeug es nicht tut; die Vorlage heißt, dass es davon abhängt, was die Vorlage mitbringt.

	Repo Blueprint	Template-Repository	Cookiecutter + cruft	Andere Copier-Vorlagen	projen
Änderungen der Vorlage nach dem Kopieren	ein Bot bringt jede Version als Pull Request	—	`cruft update` von Hand; `cruft check` scheitert, wenn es zurückliegt	`copier update` von Hand	jeder Lauf von `projen` schreibt die Dateien neu
Updates getestet, bevor sie ankommen	an jeder Art und an den echten Repositories	—	—	die Vorlage	—
Code, der beim Kopieren läuft	keiner; danach `blueprint.py create` aus der Kopie, das du selbst startest	keiner	die Hooks der Vorlage, falls es welche gibt	die Tasks, Migrationen und Erweiterungen der Vorlage, falls es welche gibt, mit `--trust`	`.projenrc` bei jedem Lauf
Was ein neues Repository braucht	Git, Python, uv und die GitHub CLI	einen Knopf auf GitHub	Python und `cookiecutter`	Python und `copier`	Node und `npx projen new`
Einstellungen des Repositorys	als Code, mit einem Bot gegen Abweichungen	—	die Vorlage	die Vorlage	—
Releases	release-please, signierte Tags, SLSA Build Level 3, SBOM, VEX, geprüft	die Vorlage	die Vorlage	die Vorlage	nach npm, und mit jsii nach PyPI, Maven, NuGet und Go
Sicherheitsprüfungen	CodeQL, Scorecard, zizmor, OSV-Scanner, Harden-Runner, ein Secret-Scan, Actions auf Commits festgelegt	die Vorlage	die Vorlage	die Vorlage	die Vorlage
Updates der Abhängigkeiten	Renovate, mit Regeln für den Merge und einem Dashboard	die Vorlage	die Vorlage	die Vorlage	ein Workflow, der sie aktualisiert
Arten von Projekten	sieben, von Home Assistant bis zu Containern	eine je Vorlage	Tausende Vorlagen, je ein Stack	copier-uv: Python; cookie: Python mit vielen Build-Backends	TypeScript, AWS CDK, jsii, Python, Java und mehr
Systeme in der CI	Linux, auf jedem Kern	die Vorlage	die Vorlage	copier-uv und cookie: Linux, macOS und Windows	die Vorlage
Prüfung beliebiger Repositories	—	—	—	cookie: sp-repo-review	—
Sichtung von Issues	der Issue-Assistent	—	—	—	—

Wo ein anderes Werkzeug besser passt¶

Eine Kopie per Knopf und sonst nichts. Ein Template-Repository von GitHub braucht keine Werkzeuge, keine Fragen und keine App und ist der einfachste Start für ein Repository, das seiner Vorlage später nicht folgen soll.
Mehrere Systeme in der CI und uv für das Projekt. copier-uv und scientific-python/cookie testen auf Linux, macOS und Windows mit mehreren Versionen von Python, und copier-uv verwaltet das Projekt mit uv. Ein Repository des Blueprints testet auf einem Linux-Runner, auf jedem Kern, und installiert seine Werkzeuge in der CI mit uv aus Lock-Dateien mit Hashes; nur der Blueprint selbst führt seine Prüfungen auch unter Windows aus.
Eine Prüfung beliebiger Repositories. sp-repo-review prüft ein Repository gegen den Entwicklungsleitfaden von Scientific Python, auch eines, das keine Vorlage gemacht hat. Die Prüfungen des Blueprints sehen auf Repositories, die aus ihm entstanden sind.
Eine Wahl der Build-Backends. cookie bietet eine Vorlage für Hatchling, Flit, PDM, Poetry, setuptools, scikit-build-core, meson-python, maturin und weitere; der Blueprint baut Python mit Hatchling.
Projekte, die in Code definiert sind. projen passt vor allem zu AWS CDK und jsii, deren viele Dateien es aus einer Definition in Code hält.
Einfachheit. Ein Repository des Blueprints startet mit mehr als 30 Workflows, einer Release-App und Einstellungen als Code. Ein kleines Projekt, das nichts davon will, ist mit einer kleineren Vorlage besser bedient.

Eines anlegen¶

Der Schnellstart legt ein Repository mit drei Befehlen an, und jede Art von Projekt hat eine eigene Seite: Home-Assistant-Integration, Nextcloud-App, GitHub Action, Python-Paket, Node-Paket, Container-Image und Repository ohne Build.