他の言語: English, Español, Português · 日本語のガイド一覧
開示: Carbon Forge は 100monkeys.ai で開発しているため、作り手による説明として読んでください。このガイドは公開ドキュメント、主に Code and files on the substrate の "Cut a release" と "Publish to git" の節、カタログページ Archives、Source control settings をもとに当社の AI エージェントが下書きし、当社がレビューしました。この日本語版は英語の原文ガイドの翻訳です。呼び出しはすべてドキュメント自身の例で、引用は英語のまま示し訳を添えています。ドキュメントが答えていない点は、最後の節に書いています。
2 文で言うモデル
"A cut names the whole workspace's state at one moment and never moves."(カットはある瞬間のワークスペース全体の状態に名前を付け、決して動かない。)"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."(git アーカイブはコードツリーを git としてレンダリングする。ツリーのリビジョンごとに 1 コミット、そのメッセージはランディングの意図。カットごとに注釈付きタグ refs/tags/nn/<cut>、そのメッセージはカットのノートを運ぶ。)レンダリングは "from the record byte for byte, so the same revision always renders to the same commit"(記録からバイト単位で行われ、同じリビジョンは常に同じコミットになる)ので、GitHub 上のコピーはいつでも記録と照合できます。
ステップ 1. リリースに含める作業をランディングする
カットが名前を付けるのはトランクなので、まだレーンにあるものは含まれません。リリースに属するものを先にランディングしてください。意図は feat、fix、docs、chore、revert のいずれかで始めます。その最初の語で、ノートは各ランディングをまとめます(コードの変更とそのドキュメントを 1 つのチェンジセットでランディングするで 1 回のランディングを追っています)。
ステップ 2. リリースを切る
snapshots.cut { "name": "v1.4.0" }カットは恒久的です。パラダイムのページは "the database refuses to change or remove a snapshot or a cut while the workspace exists"(ワークスペースが存在する間、データベースはスナップショットやカットの変更・削除を拒否する)と書いています。snapshots.materialize はカットが保持するとおりに任意のエンティティを読み、trees.diff と trees.grep もスナップショットを受け付けます。
ステップ 3. リリースノートを読む
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"(2 つのカットの間にランディングされたすべてのチェンジセットを、意図の最初の語でまとめて一覧する)もので、それぞれのランディング元のレーンと触れたパスも示します。path_glob でワークスペースの一部に絞れます。アプリでは /<workspace>/cuts/<name> が同じノートを Notes from <previous cut> という見出しで開き、Compare with another cut で任意の 2 つを選べます。
ステップ 4. GitHub アカウントをインスタンスに接続する
プッシュは "as the instance's GitHub App"(インスタンスの GitHub App として)行われるため、App はリポジトリを所有するアカウントにインストールされている必要があります。インスタンス管理者が Settings → Instance → Source control を開いて Connect a GitHub account を押すと、ブラウザは "GitHub's install page for the CarbonForge.dev GitHub App"(CarbonForge.dev GitHub App の GitHub インストールページ)に移ります。そこでアカウントまたは組織とリポジトリを選びます。ドキュメントが挙げる権限は次のとおりです。
- Contents: Read and write。コミット、
refs/heads/main、カットのタグをプッシュするため。 - Workflows: Read and write。プッシュが
.github/workflows/以下のファイルを追加・変更するときだけ必要です。ないと "GitHub refuses"(GitHub が拒否する)。 - Actions: Read。ステップ 8 でリモートの実行を読むため。
Carbon Forge に戻ると、タブに Connected to @<account> と表示されます。
ステップ 5. git アーカイブをレンダリングして検証する
archives.render { "tree": "app", "cut": "v1.4.0" }
archives.verify { "tree": "app", "cut": "v1.4.0" }render はツリーのコミットとカットのタグをアーカイブに書き込み、verify はアーカイブの状態と、あれば最初の差分を報告します。カットのページでは、ワークスペース管理者に同じ Render と Verify のボタンがあり、それぞれの答えがそのまま表示されます: Rendered: tag <id>、Verify: <status>。
ステップ 6. リモートを設定する
archives.set_remote { "tree": "app", "remote": "https://github.com/acme/app.git" }リモートは https://github.com/<owner>/<repo>.git の形で書きます。これは Settings → Workspace → Source control にある各リポジトリの Remote 欄でもあります。設定にはワークスペース管理者の権限が必要です。"because the remote decides where the archive is published"(リモートがアーカイブの公開先を決めるから)。
ステップ 7. プッシュする
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."(プッシュはリモートに足りないものだけを、fast-forward のみで、インスタンスの GitHub App として送り、main を後退させたりタグを動かしたりするくらいなら拒否する。)ジョブとしてキューに入ります(Push queued as job <id>.)。拒否は原因を名指しします。たとえば The tree <path> has no archive remote; set one with archives.set_remote, and nothing was pushed.、あるいはアーカイブが "has no rendered cut"(レンダリング済みのカットがない)と言うものです。GitHub からの拒否は、GitHub 自身の理由付きで The remote refused <ref>: <reason>. として返ります。
"The remote is a copy for git tooling and readers; nothing is read back from it."(リモートは git ツールと読み手のためのコピーであり、そこから読み戻されるものは何もない。)作業は Carbon Forge で続き、次のカットで再びプッシュします。
ステップ 8. デプロイを読み返す
"Once a cut is pushed, its deploy can be read back"(カットをプッシュすれば、そのデプロイを読み返せる)。archives.deploy_status は、カットのコミットに対するリモートの GitHub Actions の実行を最大 100 件、要約付きで返し、"and the record still takes nothing from the remote"(それでも記録はリモートから何も取り込まない)。カットの一覧は各ツリーに pushed、tagged、not rendered のいずれかの印を付けます。cut.taken や archive.pushed の webhook を使えば、ポーリングなしでデプロイスクリプトに知らせられます。
ドキュメントが答えていないこと
- すでに履歴のあるリポジトリへの最初のプッシュ。プッシュは fast-forward のみで
mainの後退を拒否します。ドキュメントはオプトインの履歴書き換えを説明していますが、無関係な既存のmainがある場合の手順は示していません。 - GitHub 以外のホスト。ドキュメントのリモートはすべて GitHub の URL です。
- セルフホストのデプロイが CarbonForge.dev の App を使えるのか、自前で登録する必要があるのか。設定ページはオペレーター設定を挙げていますが、この選択には触れていません。