release-kotlin-library

发布 Kotlin 库

核心原则

发布已准备就绪、经过验证且经用户批准的发布提交，并且只有在验证其构件和 Git 状态后，才将发布标记为完成。

前置条件

无论是在本地运行还是通过标签触发的 CI，此技能都依赖 gradle-maven-publish-plugin（com.vanniktech.maven.publish）发布库。 API 快照支持假设存在由 Metalava 生成的 api/api.txt 文件；如果仓库不维护这些文件，请禁用快照。

流程

1. 明确审查范围，并检查仓库说明、Git 状态、发布历史、版本属性、发布配置和必需的检查。 如果用户将审查限制在已提供的状态，则不要运行任何命令，并将未提供的状态标记为未知。根据构建文件或已提供的仓库事实，确认已发布模块是否直接应用 com.vanniktech.maven.publish，或通过约定插件应用；仅声明插件不足以证明已应用。如果缺少该插件或无法确认，则报告并在进行发布变更前停止；不要安装或迁移发布插件。 区分就绪情况审查、准备工作和明确的发布授权；继续之前，选择相应的结束路径。 对于恢复或恢复审查，在分析前选择并阅读恢复答复模板。对于与变更日志相关的审查，还要阅读变更日志流程。 对于准备工作或仅处理变更日志的任务，在分析前通过单独一次调用完整阅读准备答复模板。 审查过程保持只读，包括凭据。遵循现有的本地或 CI 发布机制；不要迁移。配置随附脚本前，先阅读辅助脚本约定。 对不受支持的布局或含糊的目标位置，在进行变更前停止。
2. 开始准备前，完整阅读变更日志流程；消除基线、版本和覆盖范围方面的歧义。不要猜测或创建变更日志。
3. 确认仓库的发布检查，包括测试，以及已配置的 Metalava API 生成和兼容性检查。创建快照前确认 API 文件为最新；辅助脚本只会复制这些文件，不会运行 Metalava。不要将其他 API 转储格式视为 Metalava 快照。 发布代码必须有通过检查的证据；相关变更发生后，父提交为绿色不足以作为依据。运行 Gradle 时，使用 gradle-run，除非明确授权扫描，否则添加 --no-scan。在授权范围内修复失败的检查；否则，报告失败的门禁和下一步操作后停止。
4. 使用明确的版本、路径、标题样式、API 快照适用性、分支、远程仓库、标签和命令参数来配置并预检辅助脚本。 将配置和证据保存在受版本控制的发布文件之外。写入前检查暂存区索引、快照冲突以及本地和远程目标。 本地发布时，将 ~/.env 作为数据加载，绝不要通过 shell 执行或打印其内容。 保留明确设置的进程环境变量。缺少必需凭据时，禁止本地发布；不要索取或记录凭据值。对于由标签触发的 CI，使用现有的 Git 身份验证和 CI 管理的发布密钥，不要加载或要求本地 dotenv 值。
5. 准备发布：更新版本，敲定变更日志标题和适用的已发布模块 API 快照，运行已配置的检查，并且只提交发布文件。 最终确定稳定版条目时，先根据覆盖范围台账中所有仍有效的行，以最终行为描述撰写稳定版摘要；然后将该周期原有的预发布条目放在一个 <details> 块中，并使用 <summary>Prerelease history</summary>。将原有预发布条目作为一个整体移动，不要调整顺序。保留其标题、锚点、日期和文本，并在包含的 Markdown 内容前后留空行。较早的稳定版条目应保留在该块之外。如果渲染器不支持可折叠 HTML，则保留展开的条目。 交接前，根据所有仍有效的台账行重新核对实际的稳定版摘要，并根据源顺序核对分组后的历史记录。检查最终生成的提交。验证结果必须对应此状态；如果相关代码发生变化，则验证失效。准备期间辅助脚本不得发布。
6. 发布前，向用户展示已准备好的发布内容，征求其明确批准：发布版本和标签、定稿的变更日志（或说明其不存在）、下一个开发版本、发布提交、构件坐标和目标位置、发布机制以及验证结果。提供实际的发布说明或可直接审阅的差异，不要只声称内容已经准备就绪。说明本技能要求设置此审批关卡，并等待用户决定；笼统的发布请求不等于批准尚未展示的发布详情。 如果用户已批准此确切的准备发布内容，则复用该批准。如果代码、版本、说明或发布范围发生变化，则重新准备并验证修订后的发布内容，并再次取得批准。仅准备和就绪情况请求应在用户要求的范围内停止，不要征求发布批准。
7. 只有在已批准准备好的发布内容且所有关卡均通过后，才能通过仓库选定的机制从该提交发布。本地发布和由标签触发的 CI 二选一；不要同时运行两者。批准前，不得发布构件、推送发布标签或触发发布 CI。
8. 在配置的目标位置验证所有预期的构件坐标和版本，并在适用时确认 CI 已完成。确认远程标签指向准备好的提交。命令成功或标签存在本身不能作为构件证据。只有完成上述验证后，才能推进、提交、推送并验证双方约定的下一个开发版本。仅当仓库惯例要求创建 GitHub Release 时才创建并回读，且使用已定稿的发布说明。
9. 如果执行部分成功或结果不确定，则停止后续依赖性变更，并在不泄露密钥的前提下报告已验证、失败和未知的阶段。恢复前检查实时构件、工作流、标签和分支状态；绝不要盲目重复发布、覆盖远程标签、删除已发布构件或声称已回滚。只有在现有授权范围内，才能继续执行已证实的剩余操作。

完成路径

• 准备阶段，包括仅更新变更日志： 填写所选的准备阶段答复表单。展示可供实际审阅的说明或差异、剩余检查项，以及明确的后续发布审批关卡；现在不要请求审批。
• 恢复／恢复审查： 按编号分节填写所选的恢复答复表单；回复前检查所有适用的处置项。
• 已完成的发布： 报告发布版本、提交／标签、验证、制品回读、下一个开发提交，以及有条件提供的 GitHub Release URL。只有在所有适用检查均通过后，才能声称已完成。

对于就绪情况审查或阻塞问题，请说明范围更窄的结果及剩余关卡。不要泄露凭据内容或原始敏感命令输出。