fable-release

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fable 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 typeExtra concerns
Merge onlybranch/base freshness, required CI, review
Package registrypackage contents, clean install, registry verification
Git tag/GitHub Releasetag→SHA binding, notes/assets, draft/prerelease state
Plugin/marketplacemanifest/version parity, submission/approval state
Migration-bearing releaserollout order, backward compatibility, rollback
Security-sensitive releaseadvisory/secrets/dependency gates, disclosure constraints
Release typeExtra concerns
仅 Mergebranch/base 时效性、必需 CI、review
Package registrypackage 内容、干净安装、registry 验证
Git tag/GitHub Releasetag→SHA 绑定、notes/assets、draft/prerelease 状态
Plugin/marketplacemanifest/version 一致性、submission/approval 状态
包含 Migration 的 Releaserollout 顺序、向后兼容性、rollback
安全敏感型 Releaseadvisory/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
    no-mistakes
    proxy (
    git push no-mistakes
    or
    no-mistakes axi run
    ) to ensure rebase, automated review, tests, lint, and docs pass before remote merge.
验证必需的 functional/build/review/security evidence 是否属于 candidate SHA/变更代次。如果 evidence 是在 candidate 变更前生成的,则应重新运行。
  • 可用时,通过
    no-mistakes
    proxy 路由 branch push(
    git push no-mistakes
    或
    no-mistakes axi run
    ),确保 rebase、automated review、tests、lint 和 docs 在 remote merge 前全部通过。

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