Aussi en: English, Español, Português, 日本語, Deutsch, 한국어, 简体中文, Italiano, हिन्दी · Tous les guides en français

Transparence : nous développons Carbon Forge chez 100monkeys.ai, lisez donc ceci comme le récit de son fabricant. Ce guide a été rédigé par l'un de nos agents d'IA à partir de la documentation publique, principalement les sections "Cut a release" et "Publish to git" de Code and files on the substrate, la page de catalogue Archives et Source control settings, puis relu par l'entreprise ; cette édition française est une traduction du guide original en anglais. Chaque appel est l'exemple de la documentation elle-même, et les citations sont en anglais avec la traduction à côté. Là où la documentation laisse une question ouverte, la dernière section le dit.

Le modèle en deux phrases

"A cut names the whole workspace's state at one moment and never moves." (Un cut nomme l'état de tout le workspace à un instant et ne bouge jamais.) "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'archive git rend un arbre de code en git : un commit par révision de l'arbre, dont le message est l'intention de l'intégration, et un tag annoté par cut, dont le message porte les notes du cut.) Comme elle est rendue "from the record byte for byte, so the same revision always renders to the same commit" (depuis le registre octet pour octet, si bien que la même révision donne toujours le même commit), la copie GitHub peut être comparée au registre à tout moment.

Étape 1. Intégrer le travail que la release doit contenir

Un cut nomme le trunk, donc ce qui est encore sur une lane n'en fait pas partie. Intégrez d'abord ce qui appartient à la release, avec des intentions qui commencent par feat, fix, docs, chore ou revert : ce premier mot est la façon dont les notes regroupent chaque intégration (Intégrer une modification de code et sa documentation dans un seul changeset suit une intégration).

Étape 2. Créer le cut de la release

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

Le cut est permanent. La page sur le paradigme dit : "the database refuses to change or remove a snapshot or a cut while the workspace exists." (la base de données refuse de modifier ou de supprimer un snapshot ou un cut tant que le workspace existe.) snapshots.materialize lit n'importe quelle entité telle que le cut la contient, et trees.diff et trees.grep acceptent aussi un snapshot.

Étape 3. Lire les notes de version

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" (liste chaque changeset intégré entre les deux cuts, regroupé par le premier mot de son intention), avec la lane d'origine et les chemins touchés ; path_glob le restreint à une partie du workspace. Dans l'application, /<workspace>/cuts/<name> s'ouvre sur les mêmes notes, titrées Notes from <previous cut>, et Compare with another cut en choisit deux quelconques.

Étape 4. Connecter un compte GitHub à l'instance

Le push se fait "as the instance's GitHub App" (en tant que GitHub App de l'instance), donc l'App doit être installée sur le compte propriétaire du dépôt. Un administrateur de l'instance ouvre Settings → Instance → Source control et clique sur Connect a GitHub account, qui envoie le navigateur vers "GitHub's install page for the CarbonForge.dev GitHub App" (la page d'installation GitHub de la GitHub App CarbonForge.dev). Là, vous choisissez le compte ou l'organisation et les dépôts. Les permissions que liste la documentation :

Contents: Read and write, pour pousser les commits, refs/heads/main et le tag du cut.
Workflows: Read and write, nécessaire seulement quand le push ajoute ou modifie un fichier sous .github/workflows/ ; sans elle, "GitHub refuses" (GitHub refuse).
Actions: Read, pour lire les exécutions du remote à l'étape 8.

De retour dans Carbon Forge, l'onglet affiche Connected to @<account>.

Étape 5. Rendre et vérifier l'archive git

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

Render écrit les commits de l'arbre et le tag du cut dans l'archive ; verify rapporte l'état de l'archive et, s'il y en a une, la première différence. Sur la page du cut, un administrateur du workspace a les mêmes boutons Render et Verify, et chaque réponse est affichée telle quelle : Rendered: tag <id>, Verify: <status>.

Étape 6. Définir le remote

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

Le remote s'écrit https://github.com/<owner>/<repo>.git. C'est aussi le champ Remote de chaque dépôt dans Settings → Workspace → Source control. Le définir exige d'administrer le workspace, "because the remote decides where the archive is published" (parce que le remote décide où l'archive est publiée).

Étape 7. Pousser

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." (Le push n'envoie au remote que ce qui lui manque, en fast-forward uniquement, en tant que GitHub App de l'instance, et refuse plutôt que de faire reculer main ou de déplacer un tag.) Il est mis en file comme tâche (Push queued as job <id>.). Les refus nomment leur cause, par exemple The tree <path> has no archive remote; set one with archives.set_remote, and nothing was pushed., ou un refus qui dit que l'archive "has no rendered cut" (n'a aucun cut rendu). Un refus de GitHub revient sous la forme The remote refused <ref>: <reason>. avec la raison donnée par GitHub.

"The remote is a copy for git tooling and readers; nothing is read back from it." (Le remote est une copie pour les outils git et les lecteurs ; rien n'en est relu.) Le travail continue dans Carbon Forge, et le cut suivant pousse à nouveau.

Étape 8. Relire le déploiement

"Once a cut is pushed, its deploy can be read back" (Une fois un cut poussé, son déploiement peut être relu) : archives.deploy_status renvoie les exécutions GitHub Actions du remote pour le commit du cut, 100 au plus, avec un résumé, "and the record still takes nothing from the remote." (et le registre ne prend toujours rien au remote.) L'index des cuts marque chaque arbre pushed, tagged ou not rendered. Un webhook sur cut.taken ou archive.pushed prévient un script de déploiement sans polling.

Ce que la documentation laisse sans réponse

Un premier push vers un dépôt qui a déjà un historique. Le push est en fast-forward uniquement et refuse de faire reculer main ; la documentation décrit une réécriture d'historique sur demande mais ne traite pas le cas d'un main existant et sans lien.
Les hébergeurs autres que GitHub. Chaque remote de la documentation est une URL GitHub.
Si un déploiement auto-hébergé peut utiliser l'App CarbonForge.dev ou doit enregistrer la sienne ; la page des paramètres nomme les réglages de l'opérateur mais pas ce choix.

Créer une release dans Carbon Forge et la pousser sur GitHub