Anche in: English, Español, Português, 日本語, Deutsch, Français, 한국어, 简体中文, हिन्दी · Tutte le guide in italiano

Trasparenza: Carbon Forge è sviluppato da 100monkeys.ai, quindi leggete questa guida come il resoconto di chi lo costruisce. L'ha scritta in bozza uno dei nostri agenti di IA a partire dalla documentazione pubblica, soprattutto le sezioni "Cut a release" e "Publish to git" di Code and files on the substrate, la pagina di catalogo Archives e Source control settings, e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. Ogni chiamata è l'esempio della documentazione stessa, e le citazioni sono in inglese con la traduzione accanto. Dove la documentazione lascia aperta una domanda, l'ultima sezione lo dice.

Il modello in due frasi

"A cut names the whole workspace's state at one moment and never moves." (Un cut dà un nome allo stato dell'intero workspace in un momento e non si sposta mai.) "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." (L'archivio git rende un albero di codice come git: un commit per ogni revisione dell'albero, con l'intento dell'integrazione come messaggio, e un tag annotato per ogni cut, il cui messaggio porta le note del cut.) Poiché è reso "from the record byte for byte, so the same revision always renders to the same commit" (dal registro byte per byte, quindi la stessa revisione produce sempre lo stesso commit), la copia su GitHub può essere confrontata con il registro in qualsiasi momento.

Passo 1. Integrate il lavoro che la release deve contenere

Un cut nomina il trunk, quindi tutto ciò che è ancora su una lane non ne fa parte. Integrate prima ciò che appartiene alla release, con intenti che iniziano con feat, fix, docs, chore o revert: quella prima parola è il modo in cui le note raggruppano ogni integrazione (Integrare una modifica al codice e la sua documentazione in un solo changeset segue un'integrazione).

Passo 2. Create il cut della release

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

Il cut è permanente. La pagina sul paradigma dice "the database refuses to change or remove a snapshot or a cut while the workspace exists." (il database si rifiuta di modificare o rimuovere uno snapshot o un cut finché il workspace esiste.) snapshots.materialize legge qualsiasi entità com'è nel cut, e anche trees.diff e trees.grep accettano uno snapshot.

Passo 3. Leggete le note di rilascio

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" (elenca ogni changeset integrato tra i due cut, raggruppato per la prima parola del suo intento), con la lane da cui è stato integrato e i percorsi toccati; path_glob lo restringe a una parte del workspace. Nell'app, /<workspace>/cuts/<name> si apre sulle stesse note, intitolate Notes from <previous cut>, e Compare with another cut sceglie due cut qualsiasi.

Passo 4. Collegate un account GitHub all'istanza

Il push avviene "as the instance's GitHub App" (come la GitHub App dell'istanza), quindi la App deve essere installata sull'account che possiede il repository. Un amministratore dell'istanza apre Settings → Instance → Source control e preme Connect a GitHub account, che porta il browser alla "GitHub's install page for the CarbonForge.dev GitHub App" (pagina di installazione di GitHub per la GitHub App CarbonForge.dev). Lì scegliete l'account o l'organizzazione e i repository. I permessi che elenca la documentazione:

Contents: Read and write, per fare il push dei commit, di refs/heads/main e del tag del cut.
Workflows: Read and write, necessario solo quando il push aggiunge o modifica un file sotto .github/workflows/; senza, "GitHub refuses" (GitHub rifiuta).
Actions: Read, per leggere le esecuzioni del remote al passo 8.

Tornati in Carbon Forge, la scheda mostra Connected to @<account>.

Passo 5. Rendete e verificate l'archivio git

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

Render scrive i commit dell'albero e il tag del cut nell'archivio; verify riporta lo stato dell'archivio e, quando c'è, la prima differenza. Nella pagina del cut, un amministratore del workspace ha gli stessi pulsanti Render e Verify, e ogni risposta è mostrata alla lettera: Rendered: tag <id>, Verify: <status>.

Passo 6. Impostate il remote

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

Il remote si scrive https://github.com/<owner>/<repo>.git. È anche il campo Remote di ogni repository in Settings → Workspace → Source control. Impostarlo richiede l'amministrazione del workspace, "because the remote decides where the archive is published" (perché il remote decide dove viene pubblicato l'archivio).

Passo 7. Fate il push

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." (Il push invia al remote solo ciò che gli manca, solo fast-forward, come la GitHub App dell'istanza, e rifiuta piuttosto che spostare main indietro o spostare un tag.) Viene accodato come job (Push queued as job <id>.). I rifiuti nominano la loro causa, per esempio The tree <path> has no archive remote; set one with archives.set_remote, and nothing was pushed., oppure uno che dice che l'archivio "has no rendered cut" (non ha un cut reso). Un rifiuto di GitHub torna come The remote refused <ref>: <reason>. con il motivo di GitHub stesso.

"The remote is a copy for git tooling and readers; nothing is read back from it." (Il remote è una copia per gli strumenti git e per chi legge; da lì non si rilegge nulla.) Il lavoro continua in Carbon Forge, e il cut successivo fa di nuovo il push.

Passo 8. Rileggete il deploy

"Once a cut is pushed, its deploy can be read back" (Una volta fatto il push di un cut, il suo deploy si può rileggere): archives.deploy_status risponde con le esecuzioni GitHub Actions del remote per il commit del cut, al massimo 100, con un riepilogo, "and the record still takes nothing from the remote." (e il registro continua a non prendere nulla dal remote.) L'indice dei cut segna ogni albero come pushed, tagged o not rendered. Un webhook su cut.taken o archive.pushed avvisa uno script di deploy senza polling.

Cosa la documentazione lascia senza risposta

Un primo push verso un repository che ha già una storia. Il push è solo fast-forward e rifiuta di spostare main indietro; la documentazione descrive una riscrittura della storia su richiesta ma non tratta il caso di un main esistente e non correlato.
Host diversi da GitHub. Ogni remote nella documentazione è un URL GitHub.
Se un'installazione self-hosted possa usare la App CarbonForge.dev o debba registrarne una propria; la pagina delle impostazioni nomina le impostazioni dell'operatore ma non questa scelta.

Creare una release in Carbon Forge e pubblicarla su GitHub