fable-release
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseFable Release
Fable Release
Prove that the exact commit and artifact users will receive are ready to ship, then distinguish readiness from actual distribution.
证明用户将收到的确切 commit 和 artifact 已准备好发布,并区分“具备发布条件”与“实际完成分发”。
Mission
Mission
A release is an external state transition. Source tests can be perfect while the package omits files, the tag points at another commit, the registry still serves an old version, or a published artifact cannot start in a clean environment.
This Skill closes that gap by tying release claims to exact version, commit, artifact, workflow, tag, and registry evidence.
发布(release)是一次外部状态转换。Source 测试可能全部通过,但 package 仍可能遗漏文件、tag 指向另一个 commit、registry 仍在提供旧版本,或者已发布的 artifact 无法在干净环境中启动。
此 Skill 通过将 release 声明与确切的 version、commit、artifact、workflow、tag 和 registry 证据绑定,弥补这一缺口。
Activate When
Activate When
- preparing a branch for merge or a version for release;
- creating/pushing a version tag;
- publishing npm/package/plugin artifacts;
- finalizing a GitHub Release;
- verifying that a distribution channel actually serves the intended version;
- assessing whether release evidence is current after last-minute changes.
- 准备待 merge 的 branch,或准备用于 release 的 version;
- 创建/推送 version tag;
- 发布 npm/package/plugin artifact;
- 完成 GitHub Release;
- 验证 distribution channel 实际提供预期 version;
- 评估 last-minute 变更后 release evidence 是否仍为最新。
Do Not Activate When
Do Not Activate When
- implementation is still changing (/
fable-execute);fable-tdd - functional verification is incomplete ();
fable-verify - blocking review/security findings remain;
- the user has not authorized an irreversible publish action. Readiness checks may run; publishing itself requires the applicable authorization.
- 实现仍在变更中(/
fable-execute);fable-tdd - functional verification 尚未完成();
fable-verify - 阻塞性的 review/security finding 仍未解决;
- 用户尚未授权不可逆的 publish 操作。可以执行就绪检查,但实际发布仍需获得适用授权。
Release Classification
Release Classification
| Release type | Extra concerns |
|---|---|
| Merge only | branch/base freshness, required CI, review |
| Package registry | package contents, clean install, registry verification |
| Git tag/GitHub Release | tag→SHA binding, notes/assets, draft/prerelease state |
| Plugin/marketplace | manifest/version parity, submission/approval state |
| Migration-bearing release | rollout order, backward compatibility, rollback |
| Security-sensitive release | advisory/secrets/dependency gates, disclosure constraints |
| Release type | Extra concerns |
|---|---|
| 仅 Merge | branch/base 时效性、必需 CI、review |
| Package registry | package 内容、干净安装、registry 验证 |
| Git tag/GitHub Release | tag→SHA 绑定、notes/assets、draft/prerelease 状态 |
| Plugin/marketplace | manifest/version 一致性、submission/approval 状态 |
| 包含 Migration 的 Release | rollout 顺序、向后兼容性、rollback |
| 安全敏感型 Release | advisory/secrets/dependency 门禁、disclosure 限制 |
Protocol
Protocol
Stage 1 — Freeze the candidate
Stage 1 — 冻结候选版本
Identify the exact candidate:
- version;
- commit SHA;
- target branch/tag;
- distribution channels;
- required CI/review/security evidence.
Any source/config/package mutation after this point invalidates relevant release evidence and creates a new candidate.
确定确切的 candidate:
- version;
- commit SHA;
- target branch/tag;
- distribution channel;
- 必需的 CI/review/security evidence。
此后的任何 source/config/package 变更都会使相关 release evidence 失效,并产生新的 candidate。
Stage 2 — Validate version semantics
Stage 2 — 校验版本语义
Check:
- version does not already exist in target registry/tag namespace;
- SemVer matches actual compatibility impact;
- all canonical version locations/manifests agree;
- changelog/release notes describe user-visible changes accurately;
- prerelease state is intentional.
Do not choose patch/minor/major purely for convenience.
检查:
- version 尚未存在于目标 registry/tag namespace;
- SemVer 与实际兼容性影响一致;
- 所有 canonical version location/manifest 均保持一致;
- changelog/release notes 准确描述用户可见的变更;
- prerelease 状态是刻意设定的。
不要仅为了方便而选择 patch/minor/major。
Stage 3 — Reconfirm fresh quality gates
Stage 3 — 重新确认最新质量门禁
Verify required functional/build/review/security evidence belongs to the candidate SHA/mutation generation. If evidence was produced before candidate changes, rerun it.
- When available, route branch pushes through the proxy (
no-mistakesorgit push no-mistakes) to ensure rebase, automated review, tests, lint, and docs pass before remote merge.no-mistakes axi run
验证必需的 functional/build/review/security evidence 是否属于 candidate SHA/变更代次。如果 evidence 是在 candidate 变更前生成的,则应重新运行。
- 可用时,通过 proxy 路由 branch push(
no-mistakes或git push no-mistakes),确保 rebase、automated review、tests、lint 和 docs 在 remote merge 前全部通过。no-mistakes axi run
Stage 4 — Inspect the artifact boundary
Stage 4 — 检查 artifact 边界
Build/dry-run the exact artifact and inspect its manifest/content.
Check:
- required entrypoints/assets/manifests are present and non-empty;
- secrets, temp files, tests/fixtures/internal holdouts are excluded unless intentionally public;
- generated files are current;
- executable permissions/exports/bin paths are correct;
- dependency/runtime constraints are accurate.
构建并 dry-run 确切的 artifact,然后检查其 manifest/content。
检查:
- 必需的 entrypoints/assets/manifests 均已存在且非空;
- 除非有意公开,否则不得包含 secrets、临时文件、tests/fixtures/internal holdouts;
- generated files 保持最新;
- executable permissions/exports/bin paths 正确;
- dependency/runtime constraints 准确无误。
Stage 5 — Clean-environment smoke
Stage 5 — 干净环境 smoke
Install/use the produced artifact outside the source checkout where feasible.
Prove at least:
- install succeeds;
- primary executable/import resolves;
- version/help/basic smoke works;
- documented quick-start path is not accidentally relying on repo-local files.
在可行的情况下,在 source checkout 之外安装或使用生成的 artifact。
至少证明:
- 安装成功;
- primary executable/import 可以解析;
- version/help/basic smoke 可以正常工作;
- 文档中的 quick-start 路径没有意外依赖 repo-local 文件。
Stage 6 — Verify repository release state
Stage 6 — 验证仓库 release 状态
Before publishing:
- candidate commit is pushed;
- required CI on the candidate is green;
- tag does not exist or already points to exactly the intended SHA;
- release notes/assets target the same tag/SHA;
- branch is not known-broken relative to base.
发布前:
- candidate commit 已推送;
- candidate 上必需的 CI 全部通过;
- tag 尚不存在,或已经准确指向预期 SHA;
- release notes/assets 指向同一个 tag/SHA;
- 未发现 branch 相对 base 已知损坏。
Stage 7 — Publish only through an authorized secure path
Stage 7 — 仅通过已授权的安全路径发布
Prefer configured trusted publishing/OIDC/host automation over introducing long-lived tokens.
Do not print/store credentials or weaken security to make a release pass.
If authorization or authentication is absent, stop at READY_NOT_PUBLISHED with exact remaining action.
优先使用已配置的 trusted publishing/OIDC/host automation,而不是引入 long-lived token。
不要打印或存储 credentials,也不要为了通过 release 而削弱安全性。
如果缺少 authorization 或 authentication,应停止并返回 READY_NOT_PUBLISHED,同时给出确切的后续操作。
Stage 8 — Verify distribution independently
Stage 8 — 独立验证分发结果
After publish, query the external destination rather than trusting the publish command.
Examples of proof:
- registry reports expected version/dist metadata;
- clean install from registry succeeds;
- Git tag resolves to candidate SHA;
- GitHub Release is actually public, not draft;
- marketplace status reflects submitted/published state.
发布后,应查询外部 destination,而不是直接信任 publish command。
证明示例:
- registry 报告预期的 version/dist metadata;
- 从 registry 进行干净安装成功;
- Git tag 解析到 candidate SHA;
- GitHub Release 已实际公开,而不是 draft;
- marketplace 状态反映 submitted/published 状态。
Stage 9 — Post-release smoke and handoff
Stage 9 — 发布后 smoke 与交接
Run the user-facing install/invocation path from public distribution. Record rollback/deprecation/follow-up issues if observed.
从 public distribution 运行面向用户的 install/invocation 路径。如果发现 rollback/deprecation/follow-up 问题,应予以记录。
Release Verdicts
Release Verdicts
- NOT_READY: required deterministic/review/security/artifact gate fails.
- READY_NOT_PUBLISHED: candidate is sound but publish is unauthorized/unavailable/not requested.
- PUBLISHED_UNVERIFIED: publish command/workflow claims success but external distribution has not been independently confirmed.
- RELEASED: exact candidate is public through intended channels and independently verified.
Do not collapse these states into "done."
- NOT_READY:必需的 deterministic/review/security/artifact 门禁失败。
- READY_NOT_PUBLISHED:candidate 本身可靠,但 publish 未获授权、不可用或未被请求。
- PUBLISHED_UNVERIFIED:publish command/workflow 声称成功,但尚未独立确认 external distribution。
- RELEASED:确切 candidate 已通过预期 channel 公开,并经过独立验证。
不要将这些状态统称为“完成”。
Decision Rules
Decision Rules
- A dirty worktree does not automatically fail if dirt is explicitly unrelated and release artifact is from a clean candidate SHA; however uncommitted release changes do fail readiness.
- Tag exists at different SHA → hard stop; never move/force a release tag casually.
- Package version already exists in immutable registry → choose a new valid version, do not overwrite.
- Dry-run contents differ from intended public surface → fix package configuration before tagging/publishing.
- Local global install works from repo link but clean tarball/registry install fails → NOT_READY.
- CI green on older commit → stale release evidence.
- GitHub Release draft exists → not public release evidence.
- Publish workflow green but registry not updated yet → PUBLISHED_UNVERIFIED until independently confirmed or known propagation policy is resolved.
- Marketplace requiring manual approval → report submission state accurately; never claim publication.
- dirty worktree 不会自动导致失败,前提是 dirt 明确与 release 无关,且 release artifact 来自干净的 candidate SHA;但未提交的 release 变更会使就绪状态失败。
- Tag 存在于不同 SHA → 必须停止;切勿随意移动或强制修改 release tag。
- Package version 已存在于 immutable registry → 选择新的有效 version,不要覆盖。
- Dry-run 内容与预期 public surface 不一致 → 在 tagging/publishing 前修复 package configuration。
- Local global install 可通过 repo link 运行,但 clean tarball/registry install 失败 → NOT_READY。
- CI 在较旧的 commit 上通过 → release evidence 已过期。
- GitHub Release draft 已存在 → 不能作为 public release evidence。
- Publish workflow 通过但 registry 尚未更新 → 保持 PUBLISHED_UNVERIFIED,直到完成独立确认或解决已知的 propagation policy 问题。
- Marketplace 要求 manual approval → 准确报告 submission 状态;绝不声称已经发布。
Invariants
Invariants
- Release version, commit, tag, artifact, and public metadata refer to one candidate.
- No credential is committed or logged as release evidence.
- Irreversible external writes require applicable authorization.
- Public release claims are externally verified.
- Last-minute mutation invalidates stale candidate evidence.
- Release notes do not claim maturity/features unsupported by fresh proof.
- Release version、commit、tag、artifact 和 public metadata 必须指向同一个 candidate。
- 不得将任何 credential 提交到代码库或记录为 release evidence。
- 不可逆的 external write 必须获得适用授权。
- Public release 声明必须经过外部验证。
- Last-minute mutation 会使过期的 candidate evidence 失效。
- Release notes 不得声称最新证据无法支持的成熟度或功能。
Failure Taxonomy
Failure Taxonomy
Artifact omission/pollution
Artifact 遗漏/污染
Package misses runtime file or includes secrets/internal material. Fix boundary, rebuild, resmoke.
Package 遗漏 runtime file 或包含 secrets/internal material。修复边界,重新构建并重新执行 smoke。
Version drift
Version drift
Manifests/changelog/CLI/tag disagree. Reconcile before release.
Manifest/changelog/CLI/tag 相互不一致。发布前进行协调和修正。
Candidate drift
Candidate drift
CI/evidence points to older SHA after release commit changed. Rerun gates.
Release commit 变更后,CI/evidence 仍指向较旧的 SHA。重新运行门禁。
Tag mismatch
Tag mismatch
Existing tag points elsewhere. Stop; investigate rather than force-move.
现有 tag 指向其他位置。停止操作并调查,不要强制移动 tag。
Publish/auth failure
Publish/auth 失败
Candidate may remain READY_NOT_PUBLISHED. Diagnose secure auth/workflow without embedding credentials.
Candidate 可能仍处于 READY_NOT_PUBLISHED。诊断安全的 auth/workflow,不要嵌入 credentials。
Registry/release mismatch
Registry/release 不匹配
Publish reports success but public channel serves wrong/old artifact. Keep PUBLISHED_UNVERIFIED and investigate.
Publish 报告成功,但 public channel 提供错误或旧版 artifact。保持 PUBLISHED_UNVERIFIED 并进行调查。
Clean-install failure
Clean-install 失败
Artifact depends on repo-local files/dev state. NOT_READY regardless of source tests.
Artifact 依赖 repo-local 文件或开发环境状态。无论 source tests 结果如何,均为 NOT_READY。
Anti-Patterns
Anti-Patterns
- "tests pass, publish";
- tagging before inspecting artifact contents;
- using source checkout as the only install test;
- force-moving tags;
- adding tokens to config/docs to bypass trusted publishing;
- equating draft release with public release;
- trusting workflow success without registry/release lookup;
- updating docs to claim availability before public verification;
- claiming 100% maturity while changed behavioral evidence is stale.
- “测试通过,直接发布”;
- 在检查 artifact 内容前创建 tag;
- 仅使用 source checkout 作为安装测试;
- 强制移动 tag;
- 为绕过 trusted publishing 而向 config/docs 中添加 token;
- 将 draft release 等同于 public release;
- 未查询 registry/release 就信任 workflow 成功;
- 在完成 public verification 前更新 docs 并声称已经可用;
- 在行为变更的 evidence 已过期时仍声称 100% 成熟。
Release Attestation
Release Attestation
text
Version:
Candidate SHA:
Target channels:
Fresh quality gates:
Artifact manifest check:
Clean-install smoke:
Tag → SHA:
GitHub Release state:
Registry/marketplace state:
External verification:
Verdict: NOT_READY | READY_NOT_PUBLISHED | PUBLISHED_UNVERIFIED | RELEASED
Rollback/follow-up:text
Version:
Candidate SHA:
Target channels:
Fresh quality gates:
Artifact manifest check:
Clean-install smoke:
Tag → SHA:
GitHub Release state:
Registry/marketplace state:
External verification:
Verdict: NOT_READY | READY_NOT_PUBLISHED | PUBLISHED_UNVERIFIED | RELEASED
Rollback/follow-up:Completion Criteria
Completion Criteria
The Skill's work completes when the requested release stage is accurately attested:
- readiness claims are tied to exact candidate evidence;
- artifact boundary and clean install are proven where applicable;
- tag/release/registry states are consistent;
- public distribution is independently verified before ;
RELEASED - missing authorization/external gates are represented as explicit state, never guessed away.
当 requested release stage 得到准确证明时,此 Skill 的工作即告完成:
- 就绪声明与确切的 candidate evidence 绑定;
- 在适用情况下证明 artifact 边界和 clean install;
- tag/release/registry 状态保持一致;
- 在标记为 RELEASED 前独立验证 public distribution;
- 缺少 authorization/external gate 时,以明确状态表示,绝不通过猜测绕过。
Progressive Resources
Progressive Resources
- Deep guide:
references/artifact-and-distribution-verification.md - Existing release gates:
references/release-gates.md - Example:
examples/release-readiness-audit.md
- 深度指南:
references/artifact-and-distribution-verification.md - 现有 release 门禁:
references/release-gates.md - 示例:
examples/release-readiness-audit.md