También en: English, Português, 日本語 · Todas las guías en español

Aviso: construimos Carbon Forge en 100monkeys.ai, así que lee esto como el relato de quien lo fabrica. Esta guía la redactó uno de nuestros agentes de IA a partir de la documentación pública, sobre todo las secciones "Cut a release" y "Publish to git" de Code and files on the substrate, la página de catálogo Archives y Source control settings, y la revisó la empresa; esta versión en español es una traducción de la guía original en inglés. Cada llamada es el ejemplo de la propia documentación, y las citas van en inglés con la traducción al lado. Donde la documentación deja una pregunta abierta, la última sección lo dice.

El modelo en dos frases

"A cut names the whole workspace's state at one moment and never moves." (Un corte nombra el estado completo del espacio de trabajo en un momento y nunca se mueve.) "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." (El archivo git renderiza un árbol de código como git: un commit por cada revisión del árbol, cuyo mensaje es la intención de la integración, y una etiqueta anotada refs/tags/nn/<cut> por corte, cuyo mensaje lleva las notas del corte.) Como se renderiza "from the record byte for byte, so the same revision always renders to the same commit" (desde el registro byte a byte, así que la misma revisión siempre produce el mismo commit), la copia de GitHub se puede contrastar con el registro en cualquier momento.

Paso 1. Integra el trabajo que debe contener la versión

Un corte nombra el trunk, así que lo que siga en una lane no entra. Integra primero lo que pertenece a la versión, con intenciones que empiecen por feat, fix, docs, chore o revert: esa primera palabra es la que usan las notas para agrupar cada integración (Integra un cambio de código y su documentación en un solo changeset recorre una integración).

Paso 2. Corta la versión

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

El corte es permanente. La página del paradigma dice "the database refuses to change or remove a snapshot or a cut while the workspace exists" (la base de datos se niega a cambiar o borrar una instantánea o un corte mientras exista el espacio de trabajo). snapshots.materialize lee cualquier entidad tal como la guarda el corte, y trees.diff y trees.grep también aceptan una instantánea.

Paso 3. Lee las notas de la versión

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" (enumera cada changeset integrado entre los dos cortes, agrupado por la primera palabra de su intención), con la lane de la que vino cada uno y las rutas que tocó; path_glob lo limita a una parte del espacio de trabajo. En la app, /<workspace>/cuts/<name> se abre con las mismas notas, bajo el encabezado Notes from <previous cut>, y Compare with another cut elige dos cualesquiera.

Paso 4. Conecta una cuenta de GitHub a la instancia

El push se hace "as the instance's GitHub App" (como la GitHub App de la instancia), así que la App debe estar instalada en la cuenta dueña del repositorio. Un administrador de la instancia abre Settings → Instance → Source control y pulsa Connect a GitHub account, que lleva el navegador a "GitHub's install page for the CarbonForge.dev GitHub App" (la página de instalación de GitHub para la GitHub App de CarbonForge.dev). Allí eliges la cuenta u organización y los repositorios. Los permisos que enumera la documentación:

Contents: Read and write, para subir commits, refs/heads/main y la etiqueta del corte.
Workflows: Read and write, necesario solo cuando el push añade o cambia un archivo bajo .github/workflows/; sin él "GitHub refuses" (GitHub lo rechaza).
Actions: Read, para leer las ejecuciones del remoto en el paso 8.

De vuelta en Carbon Forge, la pestaña muestra Connected to @<account>.

Paso 5. Renderiza y verifica el archivo git

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

Render escribe los commits del árbol y la etiqueta del corte en el archivo; verify informa del estado del archivo y, si la hay, de la primera diferencia. En la página del corte, un administrador del espacio de trabajo tiene los mismos botones Render y Verify, y cada respuesta se muestra tal cual: Rendered: tag <id>, Verify: <status>.

Paso 6. Configura el remoto

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

El remoto se escribe https://github.com/<owner>/<repo>.git. También es el campo Remote de cada repositorio en Settings → Workspace → Source control. Configurarlo exige ser administrador del espacio de trabajo, "because the remote decides where the archive is published" (porque el remoto decide dónde se publica el archivo).

Paso 7. Haz 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." (El push envía al remoto solo lo que le falta, solo con fast-forward, como la GitHub App de la instancia, y se niega antes que mover main hacia atrás o mover una etiqueta.) Queda en cola como un trabajo (Push queued as job <id>.). Los rechazos nombran su causa, por ejemplo The tree <path> has no archive remote; set one with archives.set_remote, and nothing was pushed., u otro que dice que el archivo "has no rendered cut" (no tiene ningún corte renderizado). Un rechazo de GitHub vuelve como The remote refused <ref>: <reason>. con el motivo de GitHub.

"The remote is a copy for git tooling and readers; nothing is read back from it." (El remoto es una copia para las herramientas de git y para quien lee; no se lee nada de vuelta desde él.) El trabajo sigue en Carbon Forge, y el siguiente corte vuelve a hacer push.

Paso 8. Lee el despliegue de vuelta

"Once a cut is pushed, its deploy can be read back" (una vez subido un corte, su despliegue se puede leer de vuelta): archives.deploy_status responde las ejecuciones de GitHub Actions del remoto para el commit del corte, como mucho 100, con un resumen, "and the record still takes nothing from the remote" (y el registro sigue sin tomar nada del remoto). El índice de cortes marca cada árbol como pushed, tagged o not rendered. Un webhook en cut.taken o archive.pushed avisa a un script de despliegue sin sondeos.

Lo que la documentación deja sin responder

Un primer push a un repositorio que ya tiene historial. El push es solo fast-forward y se niega a mover main hacia atrás; la documentación describe una reescritura de historial opcional, pero no recorre el caso de un main existente y sin relación.
Hosts distintos de GitHub. Todos los remotos de la documentación son URL de GitHub.
Si un despliegue autoalojado puede usar la App de CarbonForge.dev o debe registrar la suya; la página de configuración nombra los ajustes del operador, pero no esa elección.

Corta una versión en Carbon Forge y súbela a GitHub