release-kotlin-library

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Release Kotlin library

发布Kotlin库

Core principle

核心原则

Publish the prepared, validated release commit and call the release complete only after verifying its artifacts and Git state.

仅在验证制品和Git状态无误后，再发布经过准备、验证的发布提交，并宣告发布完成。

Prerequisite

前置条件

This skill relies on

gradle-maven-publish-plugin

(

com.vanniktech.maven.publish

) for library publication, whether run locally or through tag-triggered CI. API snapshot support assumes Metalava-generated

api/api.txt

files; disable snapshots when the repository does not maintain them.

本Skill依赖

gradle-maven-publish-plugin

（

com.vanniktech.maven.publish

）进行库发布，无论是本地运行还是通过标签触发的CI。API快照支持基于Metalava生成的

api/api.txt

文件；若仓库不维护该文件，请禁用快照功能。

Procedure

操作流程

Establish scope and inspect repository instructions, Git state, release history, version properties, publishing configuration and required checks. Confirm that published modules apply
```
com.vanniktech.maven.publish
```
, directly or through a convention plugin. A declaration without application is not sufficient. If absent or unverified, report the unmet prerequisite and stop before release mutations; do not install or migrate publishing plugins. Distinguish a readiness review, preparation request and explicit release authorization. Keep review requests read-only, including credentials. Follow the existing local or CI publishing mechanism; do not migrate it. Read the helper contract before configuring the bundled script. Stop before mutation on unsupported layouts or ambiguous destinations.
Resolve the previous applicable release using tag conventions and ancestry. An ambiguous baseline needs resolution, not a lexically highest tag guess. Use supplied release and next development versions. Propose and confirm each missing value before mutation; do not silently increment a prerelease to the next patch snapshot.
If
```
CHANGELOG.md
```
exists, compare its
```
Unreleased
```
section against the complete changes since the baseline: inspect history, diffs and relevant issue or PR evidence. Preserve curated wording, add missing consumer-visible changes, correct inaccurate entries, and omit internal-only changes with no consumer impact. Resolve uncertain coverage before publication. Report reviewed scope and unresolved gaps; a heading check cannot prove semantic completeness. Preserve existing formatting and prior release entries. If the file is absent, skip this step without creating it. Commit only authorized changelog corrections before invoking preparation, so its clean-worktree gate holds.
Identify repository release checks, including tests and Metalava API generation and compatibility checks where configured. Confirm that API files are current before snapshotting; the helper copies them without running Metalava. Do not treat other API dump formats as Metalava snapshots. Require passing evidence for the release code; a green parent commit is insufficient after relevant changes. For Gradle execution, use gradle-run, with
```
--no-scan
```
unless a scan is explicitly authorized. Fix failed checks within authorized scope; otherwise stop with the failing gate and next action.
Configure and preflight the helper with explicit versions, paths, heading style, API snapshot applicability, branch, remote, tag and command arguments. Keep configuration and evidence outside tracked release files. Check the index, snapshot collisions and local/remote destinations before writes. Load
```
~/.env
```
for local publication as data, never by shell sourcing or printing it. Preserve explicit process environment values. Missing required credentials block local publication; do not request or log their values. For tag-triggered CI, use existing Git authentication and CI-managed publishing secrets without loading or requiring local dotenv values.
Prepare the release: update the version, finalize the changelog heading and applicable published-module API snapshots, run configured checks, and commit only release files. Inspect the resulting commit. Bind validation evidence to this state and invalidate it if relevant code changes. The helper must not publish during preparation.
When release is authorized and all gates pass, publish from that commit via the repository's selected mechanism. Local publication and tag-triggered CI are alternatives; do not run both. An explicit release request needs no redundant final approval. Preparation-only requests stop at prepared state.
Verify all expected artifact coordinates and versions at the configured destination, along with CI completion when applicable. Verify the remote tag resolves to the prepared commit. A successful command or tag alone is not artifact evidence. Only then advance, commit, push and verify the agreed next development version. Create and read back a GitHub Release only when repository conventions call for it, using the finalized release notes.
On partial or uncertain success, stop dependent mutations and report verified, failed and unknown stages without secrets. Inspect live artifact, workflow, tag and branch state before recovery; never blindly repeat publication, overwrite remote tags, delete published artifacts or claim rollback. Resume only a proven remaining action within existing authorization.

确定范围并检查仓库说明、Git状态、发布历史、版本属性、发布配置和所需检查项。确认待发布模块已应用
```
com.vanniktech.maven.publish
```
（直接应用或通过约定插件应用）。仅声明但未应用该插件不符合要求。若插件缺失或无法确认，报告未满足的前置条件，在执行发布变更前终止操作；不要安装或迁移发布插件。区分就绪状态审查、准备请求和明确的发布授权。审查请求需保持只读，包括凭证信息。遵循现有的本地或CI发布机制，不要进行迁移。配置内置脚本前请阅读辅助脚本约定。若遇到不支持的目录结构或不明确的发布目标，在执行变更前终止操作。
依据标签约定和提交祖先链确定上一个有效发布版本。基线不明确时需要明确解决，不能猜测词法排序最高的标签。使用提供的发布版本和下一个开发版本。所有缺失的值都需在变更前提出并确认；不要静默地将预发布版本递增到下一个补丁快照。
若存在
```
CHANGELOG.md
```
，将其
```
Unreleased
```
部分与基线以来的完整变更进行比对：检查提交历史、diff以及相关的issue或PR凭证。保留经过整理的措辞，补充缺失的对用户可见的变更，修正不准确的条目，省略无用户影响的内部变更。发布前需解决覆盖范围不明确的问题。报告已审查的范围和未解决的缺口；仅检查标题无法证明语义完整性。保留现有格式和之前的发布条目。若该文件不存在，跳过此步骤，不要创建。在调用准备流程前，仅提交已授权的变更日志修正，以满足工作树干净的门禁要求。
确认仓库的发布检查项，包括测试以及配置了的Metalava API生成和兼容性检查。快照操作前需确认API文件是最新的；辅助脚本仅复制文件，不会运行Metalava。不要将其他API导出格式视为Metalava快照。发布代码必须有通过检查的凭证；相关变更发生后，仅父提交CI通过并不充分。执行Gradle命令时使用gradle-run，除非明确授权生成扫描报告，否则需添加
```
--no-scan
```
参数。在授权范围内修复检查失败的问题；否则需在失败门禁处终止，并说明后续操作。
使用明确的版本、路径、标题样式、API快照适用性、分支、远程仓库、标签和命令参数配置辅助脚本并进行预检查。配置和验证凭证需保存在被跟踪的发布文件之外。写入前检查暂存区、快照冲突以及本地/远程目标。本地发布时将
```
~/.env
```
作为数据加载，绝不要通过shell source或打印该文件的方式加载。保留明确的进程环境变量值。缺少所需凭证时需阻止本地发布；不要请求或记录凭证值。对于标签触发的CI，使用现有的Git认证和CI管理的发布密钥，不要加载或要求本地dotenv文件。
准备发布：更新版本、最终确定变更日志标题和适用的发布模块API快照、运行配置的检查项，且仅提交发布相关文件。检查生成的提交。将验证凭证与该状态绑定，若相关代码发生变更则凭证失效。准备阶段辅助脚本不得执行发布操作。
当发布获得授权且所有门禁都通过时，通过仓库选定的机制从该提交执行发布。本地发布和标签触发的CI二选一，不要同时运行。明确的发布请求无需冗余的最终审批。仅准备类请求在准备完成后即终止。
在配置的目标位置验证所有预期的制品坐标和版本，若适用还需验证CI已完成。验证远程标签指向的是准备好的提交。仅命令执行成功或仅存在标签不能作为制品已发布的凭证。在此之后再推进、提交、推送并验证约定的下一个开发版本。仅当仓库约定要求时，才使用最终确定的发布说明创建并回读GitHub Release。
若发布部分成功或结果不确定，停止所有依赖此的变更，并报告已验证、失败和未知的阶段，不得泄露机密。恢复前检查线上制品、工作流、标签和分支状态；绝不要盲目重复发布、覆盖远程标签、删除已发布的制品或声称已回滚。仅在现有授权范围内，恢复已确认的剩余操作。

Finish gate

完成门禁

Report the release version, release commit/tag, validation evidence, artifact readback, next development commit and conditional GitHub Release URL. Claim completion only when every applicable check passes. For review, preparation or blocked work, state that narrower outcome and the remaining gate explicitly. Do not expose credential contents or raw sensitive command output.

报告发布版本、发布提交/标签、验证凭证、制品回读结果、下一个开发提交，以及（若适用）GitHub Release链接。仅当所有适用的检查都通过时，才能宣告发布完成。对于审查、准备或受阻的工作，需明确说明对应的有限结果和剩余的门禁项。不要泄露凭证内容或原始的敏感命令输出。