release-openspec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Release OpenSpec

OpenSpec发布流程

Run the OpenSpec release workflow as a resumable state machine. Inspect live GitHub state on every invocation and take only the next safe action. Do not assume an earlier invocation completed.

将OpenSpec发布工作流作为可恢复的状态机运行。每次调用时检查GitHub实时状态，仅执行下一个安全操作。不要假设之前的调用已完成。

Principles

原则

Treat
```
Fission-AI/OpenSpec
```
and
```
origin/main
```
as the release source of truth.
Default to a read-only audit when the user asks for status, readiness, or advice.
Treat a request to release, prepare a release, continue, or resume as authorization to perform the applicable release actions.
Preserve the user's checkout. Never discard unrelated changes or switch their current branch just to prepare a changeset.
Use a temporary worktree from current
```
origin/main
```
for release-authored commits when the checkout is dirty or not on
```
main
```
.
Never approve your own PR. Human review is a deliberate gate.
Treat merge-queue entry as an intermediate state, not a merge. Advance only after GitHub reports
```
mergedAt
```
and the commit is present on
```
main
```
.
Never create the automated Version Packages PR manually. The Changesets action owns it.
Never push an empty commit merely to retrigger CI. Diagnose the failed or missing run first.
Report URLs, the state reached, and the exact human action needed whenever pausing.

将
```
Fission-AI/OpenSpec
```
和
```
origin/main
```
作为发布的可信源。
当用户询问状态、就绪情况或建议时，默认执行只读审核。
将发布、准备发布、继续或恢复的请求视为执行相应发布操作的授权。
保留用户的本地检出内容。永远不要为了准备变更集而丢弃无关更改或切换当前分支。
当本地检出内容已脏或不在
```
main
```
分支时，使用基于当前
```
origin/main
```
的临时工作树来创建发布相关的提交。
永远不要批准自己创建的PR。人工审核是必不可少的环节。
将合并队列条目视为中间状态，而非已合并状态。仅当GitHub报告
```
mergedAt
```
且提交已出现在
```
main
```
分支上时，才推进流程。
永远不要手动创建自动化的Version Packages PR。该PR由Changesets动作负责生成。
永远不要仅为了重新触发CI而推送空提交。应先诊断运行失败或缺失的原因。
暂停流程时，需报告相关URL、当前到达的状态以及明确需要人工执行的操作。

Know the two PR types

了解两种PR类型

Keep these distinct in output and decisions:

Changeset PR: A normal human-authored PR that adds one or more
```
.changeset/*.md
```
files. Prefer adding a changeset to the feature/fix PR; create a catch-up changeset PR only for already-merged work that should be included.
Version Packages PR: The automated
```
changeset-release/main
```
PR titled
```
chore(release): version packages
```
. Merging or adding changesets to
```
main
```
updates this same PR. Merging it publishes the stable release.

An open Version Packages PR does not prohibit a catch-up changeset PR. It means a catch-up PR is useful only when the audit finds missing release-worthy work. Once that PR merges, wait for the existing Version Packages PR to update.

在输出内容和决策中需区分这两种PR：

Changeset PR：由人工创建的普通PR，用于添加一个或多个
```
.changeset/*.md
```
文件。优先在功能/修复PR中添加变更集；仅当已合并的工作内容需要纳入发布但未添加变更集时，才创建补充变更集PR。
Version Packages PR：由自动化生成的
```
changeset-release/main
```
分支PR，标题为
```
chore(release): version packages
```
。向
```
main
```
分支合并或添加变更集时，会更新此PR。合并该PR将发布稳定版。

已存在的Version Packages PR不会禁止创建补充变更集PR。只有当审核发现有值得发布的工作内容未被覆盖时，补充变更集PR才有用。该PR合并后，等待现有的Version Packages PR完成更新即可。

Start with a release audit

从发布审核开始

Verify the repository and tools:
- Resolve the GitHub repository with
```
gh repo view --json nameWithOwner,url
```
  .
- Require authenticated
```
gh
```
  ,
```
git
```
  , and
```
pnpm
```
  before write actions.
- Stop before release mutations if the canonical repository is not
```
Fission-AI/OpenSpec
```
  .
Refresh without modifying the worktree:
bash
```
git fetch origin main
```
Do not fetch every tag indiscriminately. This repository may contain a conflicting historical local tag, which can make
```
git fetch --tags
```
fail even though
```
origin/main
```
fetched successfully.
Find the latest stable GitHub release. Exclude drafts and prereleases; do not use
```
git describe
```
, because a beta tag may be newer than the stable baseline.
bash
```
gh release list --repo Fission-AI/OpenSpec \
  --exclude-drafts --exclude-pre-releases --limit 100 \
  --json tagName,publishedAt \
  --jq 'max_by(.publishedAt) | {tagName, publishedAt}'
```
Ensure that exact stable tag resolves locally before using it as a
```
git log
```
boundary. Fetch only that tag if it is missing. If a same-named local tag disagrees with the canonical remote, report the mismatch and use a separately resolved canonical commit; never force-rewrite the user's tag as part of an audit.
Find open release-related PRs:
bash
```
gh pr list --repo Fission-AI/OpenSpec --state open \
  --head changeset-release/main \
  --json number,title,headRefName,baseRefName,url,reviewDecision,statusCheckRollup
```
Identify the Version Packages PR by
```
headRefName == "changeset-release/main"
```
, not title alone. Separately list likely changeset PRs and inspect their files; require positive additions to
```
.changeset/*.md
```
. Do not mistake the Version Packages PR's changeset deletions for authored changesets, and do not rely on titles because a feature/fix PR may add release tracking.
Read the live release policy in
```
.changeset/README.md
```
, pending
```
.changeset/*.md
```
files on
```
origin/main
```
, and the Version Packages PR body/files when it exists.

List first-parent commits since the latest stable tag:

bash

git log --first-parent --date=short \
  --pretty=format:'%h%x09%ad%x09%s' <stable-tag>..origin/main

Map release-worthy merged PRs to existing changesets. Use PR files and changeset history; do not infer coverage from similar wording alone.
Classify the audit as:
- ```
missing-tracking
```
  : user-facing work intended for this release lacks a changeset;
- ```
awaiting-changeset-review
```
  : a suitable changeset PR already exists;
- ```
awaiting-merge-queue
```
  : an approved changeset or Version Packages PR is queued but has not landed on
```
main
```
  ;
- ```
awaiting-version-update
```
  : required changesets are on
```
main
```
  , but the Version Packages PR has not incorporated them;
- ```
awaiting-version-review
```
  : the Version Packages PR is current but lacks approval;
- ```
ready-to-publish
```
  : the Version Packages PR is current, approved, and green;
- ```
publishing
```
  : the Version Packages PR merged but artifacts are incomplete;
- ```
needs-finalization
```
  : npm, tag, and GitHub Release exist but notes are still raw;
- ```
complete
```
  : package, tag, GitHub Release, and polished notes agree.

Present a compact audit with the stable baseline, proposed version, covered changes, possible omissions, intentionally skipped internal/docs work, open PRs, and next action.

验证仓库和工具：
- 使用
```
gh repo view --json nameWithOwner,url
```
  解析GitHub仓库。
- 在执行写入操作前，确保已通过
```
gh
```
  、
```
git
```
  和
```
pnpm
```
  的身份验证。
- 如果标准仓库不是
```
Fission-AI/OpenSpec
```
  ，则停止执行发布变更操作。
在不修改工作树的情况下刷新内容：
bash
```
git fetch origin main
```
不要无差别地拉取所有标签。本仓库可能存在冲突的本地历史标签，这会导致
```
git fetch --tags
```
失败，即使
```
origin/main
```
拉取成功。
查找最新的稳定版GitHub发布。排除草稿和预发布版本；不要使用
```
git describe
```
，因为beta标签可能比稳定基线更新。
bash
```
gh release list --repo Fission-AI/OpenSpec \
  --exclude-drafts --exclude-pre-releases --limit 100 \
  --json tagName,publishedAt \
  --jq 'max_by(.publishedAt) | {tagName, publishedAt}'
```
在将该稳定标签用作
```
git log
```
边界之前，确保其在本地已解析。如果缺失，仅拉取该标签。如果同名本地标签与标准远程标签不一致，报告该不匹配情况，并使用单独解析的标准提交；审核过程中永远不要强制覆盖用户的标签。
查找与发布相关的未关闭PR：
bash
```
gh pr list --repo Fission-AI/OpenSpec --state open \
  --head changeset-release/main \
  --json number,title,headRefName,baseRefName,url,reviewDecision,statusCheckRollup
```
通过
```
headRefName == "changeset-release/main"
```
来识别Version Packages PR，而不仅仅依赖标题。单独列出可能的Changeset PR并检查其文件；要求必须向
```
.changeset/*.md
```
添加内容。不要将Version Packages PR中删除的变更集误认为是人工创建的变更集，也不要依赖标题判断，因为功能/修复PR可能也会添加发布跟踪内容。
读取
```
.changeset/README.md
```
中的实时发布策略、
```
origin/main
```
上待处理的
```
.changeset/*.md
```
文件，以及（如果存在的话）Version Packages PR的正文和文件。

列出最新稳定标签之后的第一父提交：

bash

git log --first-parent --date=short \
  --pretty=format:'%h%x09%ad%x09%s' <stable-tag>..origin/main

将值得发布的已合并PR与现有变更集关联。使用PR文件和变更集历史记录；不要仅通过相似措辞推断覆盖情况。
将审核结果分类为：
- ```
missing-tracking
```
  ：面向用户的、计划纳入本次发布的工作内容缺少变更集；
- ```
awaiting-changeset-review
```
  ：合适的Changeset PR已存在；
- ```
awaiting-merge-queue
```
  ：已批准的Changeset或Version Packages PR已进入队列，但尚未合并到
```
main
```
  分支；
- ```
awaiting-version-update
```
  ：所需变更集已在
```
main
```
  分支上，但Version Packages PR尚未整合这些变更；
- ```
awaiting-version-review
```
  ：Version Packages PR已更新，但缺少审核批准；
- ```
ready-to-publish
```
  ：Version Packages PR已更新、已批准且检查通过；
- ```
publishing
```
  ：Version Packages PR已合并，但发布产物不完整；
- ```
needs-finalization
```
  ：npm包、标签和GitHub Release已存在，但发布说明仍未完善；
- ```
complete
```
  ：包、标签、GitHub Release和完善后的发布说明一致。

提供简洁的审核报告，包含稳定基线、拟发布版本、已覆盖的变更、可能的遗漏、有意跳过的内部/文档工作、未关闭的PR以及下一步操作。

Decide changeset coverage

判断变更集覆盖范围

.changeset/README.md

rather than assuming every merged PR needs a changeset.

Include work selected for release tracking, especially:

new user-facing features or commands;
notable fixes or hotfixes;
breaking changes or deprecations;
user-visible performance improvements.

Normally skip documentation-only work, tests, CI/tooling, and internal refactors. Flag ambiguous user-visible changes instead of silently excluding them. Ask the user only when the ambiguity materially changes release scope or the semantic version; otherwise use best judgment and let PR review be the approval gate.

遵循

.changeset/README.md

中的规定，不要假设每个已合并的PR都需要变更集。

纳入被选中进行发布跟踪的工作内容，尤其是：

新的面向用户的功能或命令；
重要的修复或热修复；
破坏性变更或废弃内容；
用户可见的性能改进。

通常跳过仅涉及文档、测试、CI/工具以及内部重构的工作内容。对于模糊的用户可见变更，应标记出来而非默默排除。仅当歧义会实质性改变发布范围或语义版本时，才询问用户；否则使用最佳判断，让PR审核作为批准环节。

Create or continue a changeset PR

创建或继续Changeset PR

Do this only for

missing-tracking

If an open changeset PR already covers the missing work, reuse it. Inspect its
```
headRefName
```
, head repository, and
```
maintainerCanModify
```
; fetch that exact head branch from its owning repository into a temporary worktree, make the update there, and push back to the same PR head. Stop if the branch is not writable. Do not create a duplicate PR or replacement branch.
Read
```
.changeset/README.md
```
immediately before authoring.
Only when no suitable PR exists, create a short
```
changeset-<scope>
```
branch from current
```
origin/main
```
. Use a temporary worktree so the operator's checkout remains untouched.
Prefer one changeset per coherent release unit. A single catch-up changeset may summarize several small items selected for the same release.
Use the exact package name
```
"@fission-ai/openspec"
```
, the highest required semantic bump, only relevant headings, and user-focused descriptions.
Validate before pushing:
bash
```
pnpm exec changeset status
```
Commit, push, and open a PR whose body lists the covered merged PRs and explains why the catch-up is needed.
Stop after returning the PR URL and request human approval. Do not approve it yourself.

On a later invocation, if the PR is approved and checks are green, merge or enqueue it only when the user asked to continue or complete the release. If GitHub uses a merge queue, inspect

mergeQueueEntry

, queue checks, and

mergedAt

; remain in

awaiting-merge-queue

until the PR actually lands on

main

. Then wait for the Changesets action on

main

to update the existing Version Packages PR. Poll with concise progress updates; do not push an empty commit or another branch update, because that can dismiss approval and restart the queue.

仅在

missing-tracking

情况下执行此操作。

如果已有未关闭的Changeset PR覆盖了缺失的工作内容，则复用该PR。检查其
```
headRefName
```
、源仓库和
```
maintainerCanModify
```
；将该精确的头分支从其所属仓库拉取到临时工作树中，在那里进行更新，然后推回到同一PR的头分支。如果该分支不可写，则停止操作。不要创建重复PR或替换分支。
在创建变更集前立即阅读
```
.changeset/README.md
```
。
仅当没有合适的PR时，基于当前
```
origin/main
```
创建一个简短的
```
changeset-<scope>
```
分支。使用临时工作树，以确保操作者的本地检出内容不受影响。
优先为每个连贯的发布单元创建一个变更集。单个补充变更集可以总结多个被选入同一发布的小项内容。
使用精确的包名
```
"@fission-ai/openspec"
```
、所需的最高语义版本增量、仅相关的标题以及面向用户的描述。
推送前验证：
bash
```
pnpm exec changeset status
```
提交、推送并创建一个PR，其正文中列出所覆盖的已合并PR，并说明需要补充变更集的原因。
返回PR URL后停止操作，请求人工审核。不要自行批准该PR。

在后续调用中，如果PR已批准且检查通过，仅当用户要求继续或完成发布时，才合并或加入队列。如果GitHub使用合并队列，检查

mergeQueueEntry

、队列检查和

mergedAt

；在PR实际合并到

main

分支之前，保持

awaiting-merge-queue

状态。然后等待

main

分支上的Changesets动作更新现有的Version Packages PR。定期提供简洁的进度更新；不要推送空提交或其他分支更新，因为这可能会取消审核批准并重启队列。

Validate the Version Packages PR

验证Version Packages PR

Before calling it ready:

Confirm it targets
```
main
```
from
```
changeset-release/main
```
and is generated by the expected automation.
Enumerate every pending
```
.changeset/*.md
```
file on current
```
main
```
, excluding
```
.changeset/README.md
```
. Verify the PR consumes every one and contains the corresponding changelog content. If any pending changeset should be deferred, stop: remove or revise it through a separately reviewed change and wait for automation to regenerate the Version Packages PR before continuing.
Fetch
```
baseRefOid
```
and
```
headRefOid
```
with
```
gh pr view
```
, require
```
baseRefOid
```
to equal current
```
origin/main
```
, and create clean detached temporary worktrees for both revisions. If the head object is missing locally, fetch the immutable
```
pull/<number>/head
```
ref first. Never validate from the operator's current worktree.
In the base worktree, run
```
pnpm exec changeset status --output changeset-status.json
```
and read the expected package/version from that file. Install locked dependencies in the temporary worktree first if the Changesets CLI is unavailable.
Compare the base status and complete pending-changeset set against the head worktree:
```
package.json
```
,
```
CHANGELOG.md
```
, removed changeset files, PR body, and proposed version must all agree. This is a base-to-head comparison because the head has already consumed the changesets and cannot calculate the pending release itself.
Remove the temporary worktrees after validation, then inspect all required checks and review state with
```
gh pr view
```
/
```
gh pr checks
```
.

If current but unapproved, return the URL and pause for human approval. If approved and green, merge or enqueue only when the user asked to release or continue. With merge queue enabled, do not treat approval, auto-merge enablement, or queue entry as the stable publish trigger; wait for

mergedAt

and confirmation that the merge reached

main

在标记为就绪之前：

确认它从
```
changeset-release/main
```
分支指向
```
main
```
分支，且由预期的自动化工具生成。
枚举当前
```
main
```
分支上所有待处理的
```
.changeset/*.md
```
文件（排除
```
.changeset/README.md
```
）。验证PR已处理所有这些文件，并包含相应的变更日志内容。如果有任何待处理的变更集需要推迟，停止操作：通过单独审核的变更移除或修改该变更集，等待自动化工具重新生成Version Packages PR后再继续。
使用
```
gh pr view
```
获取
```
baseRefOid
```
和
```
headRefOid
```
，要求
```
baseRefOid
```
等于当前
```
origin/main
```
，并为两个版本创建干净的分离临时工作树。如果本地缺少头对象，先拉取不可变的
```
pull/<number>/head
```
引用。永远不要从操作者的当前工作树进行验证。
在基线工作树中，运行
```
pnpm exec changeset status --output changeset-status.json
```
，并从该文件中读取预期的包/版本。如果Changesets CLI不可用，先在临时工作树中安装锁定的依赖。
比较基线状态和完整的待处理变更集与头工作树：
```
package.json
```
、
```
CHANGELOG.md
```
、已删除的变更集文件、PR正文和拟发布版本必须全部一致。这是基线到头版本的比较，因为头版本已处理变更集，无法自行计算待发布内容。
验证完成后移除临时工作树，然后使用
```
gh pr view
```
/
```
gh pr checks
```
检查所有必需的检查和审核状态。

如果PR已更新但未获批准，返回URL并暂停等待人工审核。如果已批准且检查通过，仅当用户要求发布或继续时，才合并或加入队列。启用合并队列后，不要将审核批准、自动合并启用或队列条目视为稳定发布的触发条件；等待

mergedAt

并确认合并已到达

main

分支。

Verify stable publishing

验证稳定版发布

After the Version Packages PR merges:

Find the release workflow run for the merge commit and wait for completion.
Verify all three artifacts independently:
- ```
npm view @fission-ai/openspec@<version> version
```
- remote tag
```
v<version>
```
  points at the expected commit;
- ```
gh release view v<version>
```
  exists and is not a prerelease.
If only some artifacts exist, report partial state and resume verification before retrying any publish action. Never republish a version already on npm.
Once all artifacts exist, read references/release-notes.md, polish the GitHub Release, and verify the saved title/body.

Version Packages PR合并后：

查找该合并提交对应的发布工作流运行，等待其完成。
独立验证所有三个产物：
- ```
npm view @fission-ai/openspec@<version> version
```
- 远程标签
```
v<version>
```
  指向预期的提交；
- ```
gh release view v<version>
```
  存在且不是预发布版本。
如果仅部分产物存在，报告部分状态并恢复验证，然后再重试任何发布操作。永远不要重新发布已存在于npm上的版本。
所有产物都存在后，读取references/release-notes.md，完善GitHub Release，并验证保存的标题/正文。

Cut a beta

发布beta版

Only enter this path when the user explicitly asks for a beta or prerelease.

Run the same audit and confirm pending changesets produce a next stable version.
Explain that beta publishing does not consume changesets or replace the stable Version Packages PR.
Trigger the existing
```
release-prepare.yml
```
workflow on
```
main
```
; do not calculate or set the beta version locally.
Verify the workflow-selected version, npm
```
beta
```
dist-tag, remote tag, and prerelease GitHub Release.
Do not merge the stable Version Packages PR as part of a beta request.

仅当用户明确要求发布beta版或预发布版本时，进入此流程。

执行相同的审核，确认待处理的变更集将生成下一个稳定版本。
说明beta版发布不会消耗变更集，也不会替代稳定版的Version Packages PR。
在
```
main
```
分支上触发现有的
```
release-prepare.yml
```
工作流；不要在本地计算或设置beta版本。
验证工作流选择的版本、npm的
```
beta
```
分发标签、远程标签和预发布GitHub Release。
不要合并稳定版的Version Packages PR作为beta版请求的一部分。

Handle failures

处理失败情况

For failed CI, inspect the failing check and logs before proposing a rerun or code change.
For a stale Version Packages PR, first confirm a successful
```
push
```
run of
```
release-prepare.yml
```
occurred after the latest changeset reached
```
main
```
.
For branch divergence, let the Changesets action update its branch. Do not force-push
```
changeset-release/main
```
.
For a queued PR, inspect merge-group checks and queue state. Do not re-enqueue, update the branch, or rerun unrelated checks while it is progressing normally.
For a version that already exists on npm, stop and reconcile the tag/GitHub Release rather than incrementing or republishing implicitly.
For missing GitHub permissions or required review, report the exact gate and URL; preserve the detected state so the next invocation can resume by inspection.

对于CI失败，在建议重新运行或修改代码之前，先检查失败的检查项和日志。
对于过时的Version Packages PR，首先确认在最新变更集到达
```
main
```
分支后，
```
release-prepare.yml
```
的
```
push
```
运行已成功完成。
对于分支分歧，让Changesets动作更新其分支。不要强制推送
```
changeset-release/main
```
。
对于已进入队列的PR，检查合并组检查和队列状态。在正常推进过程中，不要重新加入队列、更新分支或重新运行无关检查。
对于已存在于npm上的版本，停止操作并协调标签/GitHub Release，而非隐式地递增版本或重新发布。
对于缺少GitHub权限或所需审核的情况，报告具体的限制环节和URL；保留检测到的状态，以便下次调用时可通过检查恢复流程。

Completion report

完成报告

Report:

released version and stable/beta channel;
changeset PR and Version Packages PR URLs, when applicable;
release workflow result;
npm package, tag, and GitHub Release verification;
release-notes finalization status;
any intentionally deferred changes.

报告内容包括：

发布的版本和稳定版/beta版渠道；
Changeset PR和Version Packages PR的URL（如有）；
发布工作流的结果；
npm包、标签和GitHub Release的验证情况；
发布说明的完善状态；
任何有意推迟的变更。