Orbit

繁體中文

English

繁體中文

English

Appearance

版本與相容性 ​

在這裡查閱 Orbit 的版本規則與穩定契約。CLI 採用 語義化版本，候選版本記錄在 repo 根目錄的 VERSION。隨附的 plugins/orbit 外掛獨立編版，只更新 skill 時可單獨發布。

發布順序 ​

  • GitHub private 演練版從 v0.0.1 開始。
  • Source repository 在 1.0 前的產品打磨期間公開；0.x release 都是 preview，title 為 Orbit vX.Y.Z (Preview)，可能包含 breaking changes。
  • v1.0.0 是第一個 stable release：下列相容性契約已有文件與測試，並已準備好 提供外部使用者使用。1.0 test matrix 記錄背後的平台證據。
  • 每個 stable release 都是 repository 可安裝的 latest release，讓預設 installer 與 orbit update 直接取得，不需要使用者選擇 release channel。
  • 帶 pre-release 後綴的 tag（例如 v1.1.0-rc.1）會以 GitHub pre-release 發布。 Installer、orbit update、Homebrew 與 Scoop 都會略過它；要安裝請指定 tag： ORBIT_VERSION=<tag>。v1.0.0 沒有經過 release candidate。
  • 已發布的 GitHub Release 不可修改；其 tag 與 assets 都不能變更或重用。 修正必須發布成新版本。

發布批次原則 ​

main 上的 commit 都是尚未發布的工作，可以累積多個彼此相關的修正。只有當 整個批次交付一個完整、能以 installed-user journey 描述並驗證的使用者成果時， 才切出 release。單一 commit 通過測試或只修好一個 edge case，本身不構成發布 邊界。

Release batch 依照下列順序 freeze：

  1. 完成相關 implementation，以及實務上最強的 journey 驗證。
  2. 一次 review 相較於前一版的完整使用者差異。
  3. 決定下一個版本並更新 VERSION；此時先不要建立 Orbit tag。
  4. 準備並 review 對使用者說明的 release notes。
  5. 執行 candidate 與 platform gates，再手動 approve 發布。Release workflow 只會在所有 gate 通過後建立 Orbit tag，失敗的 candidate 不會留下 release tag。GitHub 會在 release 發布時鎖定 tag 與完整 asset set，並產生涵蓋其 digest 與 target commit 的 immutable-release attestation。
  6. Workflow 會先驗證 release attestation 與每個發布 asset，才允許更新 package repository。Homebrew 與 Scoop 也會在取得寫入權限前重複相同的唯讀驗證。

Release notes 在 approve release workflow 時輸入，保留於 GitHub Releases， 不再累積在 source tree。內容先描述整個 batch 的使用者成果，個別修正則作為 支援細節。

Demo repository 獨立編版 ​

orbit init 會 clone orbit-demo 在 internal/distribution 的 EnvRepoRef 所 pin 的 ref，因此該 ref 必須 一直存在；不存在時 make release-check 會失敗。

Demo 不會隨每個 Orbit release 重新打 tag。它採用日曆式版本 vYEAR.MONTH.N，N 是當月第幾次發布（v2026.8.1 是八月第一個），只有 demo 本身變動時才打 tag。採用新的 demo tag 時，在同一個 commit 更新 EnvRepoRef； 這是由 demo 驅動的變更，不是切 Orbit release 的步驟。

Repository 自動化透過 make distribution-metadata 讀取這些編譯期的值。它的 orbit.distribution.v1 JSON schema 是與 Orbit 版本無關的 maintainer contract； runtime 程式仍直接使用 Go 宣告。獨立的 installer 會把 repository 預設值寫在 腳本裡，讓 curl | sh 與 irm | iex 保持自足，make test-distribution-metadata 會核對這些預設值與匯出的 metadata 一致。

先前的做法是共用 Orbit 的版本號，結果每次 Orbit release 都要替 demo 打一個 只宣告配對關係的空 tag，所以兩者現在各自編版。

Package updates 使用 private iml885203-package-sync GitHub App。只將 App 安裝到 iml885203/homebrew-tap 與 iml885203/scoop-bucket，並授予 Actions: Read and write 與 Contents: Read。將 client ID 設為 PACKAGE_SYNC_APP_CLIENT_ID repository variable，private key 設為 PACKAGE_SYNC_APP_PRIVATE_KEY repository secret。

Immutable Releases 是由 repository owner 管理的發布前提。Workflow 不持有 repository administration credential；發布後若 GitHub 沒有回報 immutable 且 已 attested 的 release，流程會 fail closed 並阻止 package promotion，但不能把 已發布的 mutable release 追溯改成 immutable。Build provenance 與 SBOM attestation 是 binary 如何產生的獨立證據；immutable-release attestation 則綁定 已發布的 tag、target commit 與 release assets。

Official direct-install 更新會在 Orbit process 內獨立消費這份 release attestation。 Binary 進入 staging 前，會把目前平台的 binary 與 checksums.txt 綁定到 attested digest；延後套用所需的 bounded evidence 會保存在本機，實際替換前再驗證 staged bytes。這個 runtime boundary 與發布流程的驗證、build provenance 各自獨立。

1.0 前的 release 之間可以有 breaking change。從 v1.0.0 起：

  • PATCH：向後相容的修正；
  • MINOR：向後相容的新功能；
  • MAJOR：可能不相容地修改穩定契約。

v1 起的穩定契約 ​

以下介面屬於相容性契約：

  • CLI command 名稱、flags、exit 行為與文件化操作流程；
  • Agent 使用的 JSON envelope 與具名 schema version；
  • Environment YAML schema 與 validation 行為；
  • 儲存於本機的 user settings。

MINOR release 可以加入 additive change。JSON consumer 必須忽略未知欄位。 移除或重新命名欄位、command、flag 或設定 key，必須建立新的具名 schema version，或發布新的 MAJOR Orbit 版本。

Orbit 沒有公開的 Go API。所有 Go package 都在 internal/ 底下，其他 module 無法 import。唯一的例外是 plugins：它必須放在它 embed 的 plugin 檔案旁邊， 同樣不是相容性契約。之後若要提供設計過的公開 API，可在 MINOR 版本新增。

未文件化的 internal implementation、daemon HTTP API、dashboard markup 與 styling、log 文字及 test fixtures 不屬於相容性契約。Daemon HTTP API 是 CLI、 dashboard 與 daemon 之間的通道；agent 與 script 應改用 CLI 的 --json 介面。

Plugin 版本 ​

Plugin 使用 YEAR.MONTH.N，其中 N 是該月第幾次 plugin release；例如 2026.8.1 代表 2026 年 8 月第一版。每次 plugin 發布都要一起更新：

  • plugins/orbit/.codex-plugin/plugin.json
  • plugins/orbit/.claude-plugin/plugin.json

兩份 manifest 必須彼此一致，但不需要等於 Orbit CLI version。只有 plugin 內容變更時才增加 plugin version。Plugin 必須偵測已安裝的 CLI，不能教導其 支援版本尚未提供的 command 或 contract。