Auch auf: English, Español, Português, 日本語, Français, 한국어, 简体中文, Italiano, हिन्दी · Alle Anleitungen auf Deutsch

Offenlegung: Wir entwickeln Carbon Forge bei 100monkeys.ai, lesen Sie dies also als Bericht des Herstellers. Einer unserer KI-Agenten hat diese Anleitung aus der öffentlichen Doku entworfen, vor allem den Abschnitten "Cut a release" und "Publish to git" von Code and files on the substrate, der Katalogseite Archives und Source control settings, und das Unternehmen hat sie geprüft; diese deutsche Ausgabe ist eine Übersetzung der englischen Originalanleitung. Jeder Aufruf ist das Beispiel der Doku selbst, und Zitate stehen auf Englisch mit der Übersetzung daneben. Wo die Doku eine Frage offenlässt, sagt es der letzte Abschnitt.

Das Modell in zwei Sätzen

"A cut names the whole workspace's state at one moment and never moves." (Ein Cut benennt den Zustand des ganzen Workspaces zu einem Zeitpunkt und bewegt sich nie.) "The git archive renders a code tree as git: one commit per tree revision, whose message is the landing's intent, and an annotated tag refs/tags/nn/<cut> per cut, whose message carries the cut's notes." (Das Git-Archiv stellt einen Codebaum als Git dar: ein Commit pro Baumrevision, dessen Nachricht die Absicht der Landung ist, und ein annotierter Tag pro Cut, dessen Nachricht die Notes des Cuts trägt.) Weil es "from the record byte for byte, so the same revision always renders to the same commit" (aus dem Datensatz Byte für Byte erzeugt wird, sodass dieselbe Revision immer denselben Commit ergibt), lässt sich die GitHub-Kopie jederzeit gegen den Datensatz prüfen.

Schritt 1. Die Arbeit landen, die das Release enthalten soll

Ein Cut benennt den Trunk, also gehört nichts dazu, was noch auf einer Lane liegt. Landen Sie zuerst, was ins Release gehört, mit Absichten, die mit feat, fix, docs, chore oder revert beginnen: Dieses erste Wort bestimmt, wie die Notes jede Landung gruppieren (Eine Codeänderung und ihre Dokumentation in einem Changeset landen begleitet eine Landung).

Schritt 2. Das Release schneiden

snapshots.cut { "name": "v1.4.0" }

Der Cut ist dauerhaft. Die Paradigmenseite sagt: "the database refuses to change or remove a snapshot or a cut while the workspace exists." (Die Datenbank weigert sich, einen Snapshot oder Cut zu ändern oder zu entfernen, solange der Workspace existiert.) snapshots.materialize liest jede Entität so, wie der Cut sie hält, und auch trees.diff und trees.grep nehmen einen Snapshot.

Schritt 3. Die Release Notes lesen

cuts.notes { "from": "v1.3.0", "to": "v1.4.0" }

cuts.notes "lists every changeset landed between the two cuts, grouped by the first word of its intent" (listet jedes zwischen den beiden Cuts gelandete Changeset, gruppiert nach dem ersten Wort seiner Absicht), mit der Lane, aus der es landete, und den berührten Pfaden; path_glob engt es auf einen Teil des Workspaces ein. In der App öffnet /<workspace>/cuts/<name> dieselben Notes unter der Überschrift Notes from <previous cut>, und Compare with another cut wählt zwei beliebige.

Schritt 4. Ein GitHub-Konto mit der Instanz verbinden

Der Push geht "as the instance's GitHub App" (als GitHub App der Instanz), also muss die App auf dem Konto installiert sein, dem das Repository gehört. Ein Instanz-Admin öffnet Settings → Instance → Source control und klickt Connect a GitHub account, was den Browser zu "GitHub's install page for the CarbonForge.dev GitHub App" (GitHubs Installationsseite für die GitHub App CarbonForge.dev) schickt. Dort wählen Sie Konto oder Organisation und die Repositories. Die Berechtigungen laut Doku:

Contents: Read and write, um Commits, refs/heads/main und den Tag des Cuts zu pushen.
Workflows: Read and write, nur nötig, wenn der Push eine Datei unter .github/workflows/ hinzufügt oder ändert; ohne sie gilt "GitHub refuses" (GitHub lehnt ab).
Actions: Read, um in Schritt 8 die Läufe des Remotes zu lesen.

Zurück in Carbon Forge zeigt der Tab Connected to @<account>.

Schritt 5. Das Git-Archiv erzeugen und prüfen

archives.render { "tree": "app", "cut": "v1.4.0" }
archives.verify { "tree": "app", "cut": "v1.4.0" }

Render schreibt die Commits des Baums und den Tag des Cuts ins Archiv; Verify meldet den Status des Archivs und, falls es einen gibt, den ersten Unterschied. Auf der Seite des Cuts hat ein Workspace-Admin dieselben Knöpfe Render und Verify, und jede Antwort wird wörtlich angezeigt: Rendered: tag <id>, Verify: <status>.

Schritt 6. Den Remote setzen

archives.set_remote { "tree": "app", "remote": "https://github.com/acme/app.git" }

Der Remote wird als https://github.com/<owner>/<repo>.git geschrieben. Er ist auch das Feld Remote jedes Repositorys unter Settings → Workspace → Source control. Ihn zu setzen erfordert Workspace-Admin, "because the remote decides where the archive is published" (weil der Remote bestimmt, wo das Archiv veröffentlicht wird).

Schritt 7. Pushen

archives.push { "tree": "app" }

"The push sends the remote only what it lacks, fast-forward only, as the instance's GitHub App, and refuses rather than move main backwards or move a tag." (Der Push sendet dem Remote nur, was ihm fehlt, nur Fast-Forward, als GitHub App der Instanz, und lehnt ab, statt main zurückzusetzen oder einen Tag zu verschieben.) Er wird als Job eingereiht (Push queued as job <id>.). Ablehnungen nennen ihre Ursache, etwa The tree <path> has no archive remote; set one with archives.set_remote, and nothing was pushed., oder eine, die sagt, dass das Archiv "has no rendered cut" (keinen erzeugten Cut hat). Eine Ablehnung durch GitHub kommt als The remote refused <ref>: <reason>. mit GitHubs eigenem Grund zurück.

"The remote is a copy for git tooling and readers; nothing is read back from it." (Der Remote ist eine Kopie für Git-Werkzeuge und Lesende; aus ihm wird nichts zurückgelesen.) Die Arbeit geht in Carbon Forge weiter, und der nächste Cut pusht erneut.

Schritt 8. Das Deployment zurücklesen

"Once a cut is pushed, its deploy can be read back" (Sobald ein Cut gepusht ist, lässt sich sein Deployment zurücklesen): archives.deploy_status liefert die GitHub-Actions-Läufe des Remotes für den Commit des Cuts, höchstens 100, mit Zusammenfassung, "and the record still takes nothing from the remote." (und der Datensatz übernimmt weiterhin nichts vom Remote.) Der Cuts-Index markiert jeden Baum als pushed, tagged oder not rendered. Ein Webhook auf cut.taken oder archive.pushed informiert ein Deploy-Skript ohne Polling.

Was die Doku nicht beantwortet

Einen ersten Push in ein Repository, das schon eine Historie hat. Der Push ist nur Fast-Forward und weigert sich, main zurückzusetzen; die Doku beschreibt ein optionales Umschreiben der Historie, behandelt aber nicht den Fall eines bestehenden, fremden main.
Andere Hosts als GitHub. Jeder Remote in der Doku ist eine GitHub-URL.
Ob eine selbst gehostete Installation die App CarbonForge.dev nutzen kann oder eine eigene registrieren muss; die Einstellungsseite nennt die Operator-Einstellungen, aber nicht diese Wahl.

Ein Release in Carbon Forge schneiden und zu GitHub pushen