Release Kotlin library
Core principle
Publish the prepared, validated release commit and call the release complete
only after verifying its artifacts and Git state.
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.
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.
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.
1---
2name: release-kotlin-library
3description: Use when preparing, publishing, or checking readiness for a new Kotlin library version in a repository using gradle-maven-publish-plugin, including release changelog reconciliation, API snapshots, and publication verification.
4metadata:
5 source: https://skillmd.com/skills/chrisbanes/release-kotlin-library
6---
7
8# Release Kotlin library
9
10## Core principle
11
12Publish the prepared, validated release commit and call the release complete
13only after verifying its artifacts and Git state.
14
15## Prerequisite
16
17This skill relies on `gradle-maven-publish-plugin` (`com.vanniktech.maven.publish`)
18for library publication, whether run locally or through tag-triggered CI.
19API snapshot support assumes Metalava-generated `api/api.txt` files; disable
20snapshots when the repository does not maintain them.
21
22## Procedure
23
241. Establish scope and inspect repository instructions, Git state, release
25 history, version properties, publishing configuration and required checks.
26 Confirm that published modules apply `com.vanniktech.maven.publish`, directly
27 or through a convention plugin. A declaration without application is not
28 sufficient. If absent or unverified, report the unmet prerequisite and stop
29 before release mutations; do not install or migrate publishing plugins.
30 Distinguish a readiness review, preparation request and explicit release
31 authorization. Keep review requests read-only, including credentials. Follow
32 the existing local or CI publishing mechanism; do not migrate it. Read the
33 [helper contract](references/helper.md) before configuring the bundled script.
34 Stop before mutation on unsupported layouts or ambiguous destinations.
352. Resolve the previous applicable release using tag conventions and ancestry.
36 An ambiguous baseline needs resolution, not a lexically highest tag guess.
37 Use supplied release and next development versions. Propose and confirm each
38 missing value before mutation; do not silently increment a prerelease to the
39 next patch snapshot.
403. If `CHANGELOG.md` exists, compare its `Unreleased` section against the complete
41 changes since the baseline: inspect history, diffs and relevant issue or PR
42 evidence. Preserve curated wording, add missing consumer-visible changes,
43 correct inaccurate entries, and omit internal-only changes with no consumer
44 impact. Resolve uncertain coverage before publication. Report reviewed scope
45 and unresolved gaps; a heading check cannot prove semantic completeness.
46 Preserve existing formatting and prior release entries. If the file is
47 absent, skip this step without creating it. Commit only authorized changelog
48 corrections before invoking preparation, so its clean-worktree gate holds.
494. Identify repository release checks, including tests and Metalava API
50 generation and compatibility checks where configured. Confirm that API files
51 are current before snapshotting; the helper copies them without running
52 Metalava. Do not treat other API dump formats as Metalava snapshots.
53 Require passing evidence for the release code; a green
54 parent commit is insufficient after relevant changes. For Gradle execution,
55 use [gradle-run](../gradle-run/SKILL.md), with `--no-scan` unless a scan is
56 explicitly authorized. Fix failed checks within authorized scope; otherwise
57 stop with the failing gate and next action.
585. Configure and preflight the helper with explicit versions, paths, heading
59 style, API snapshot applicability, branch, remote, tag and command arguments.
60 Keep configuration and evidence outside tracked release files. Check the
61 index, snapshot collisions and local/remote destinations before writes. Load
62 `~/.env` for local publication as data, never by shell sourcing or printing it.
63 Preserve explicit process environment values. Missing required credentials
64 block local publication; do not request or log their values. For tag-triggered
65 CI, use existing Git authentication and CI-managed publishing secrets without
66 loading or requiring local dotenv values.
676. Prepare the release: update the version, finalize the changelog heading and
68 applicable published-module API snapshots, run configured checks, and commit
69 only release files. Inspect the resulting commit. Bind validation evidence to
70 this state and invalidate it if relevant code changes. The helper must not
71 publish during preparation.
727. When release is authorized and all gates pass, publish from that commit via
73 the repository's selected mechanism. Local publication and tag-triggered CI
74 are alternatives; do not run both. An explicit release request needs no
75 redundant final approval. Preparation-only requests stop at prepared state.
768. Verify all expected artifact coordinates and versions at the configured
77 destination, along with CI completion when applicable. Verify the remote tag
78 resolves to the prepared commit. A successful command or tag alone is not
79 artifact evidence. Only then advance, commit, push and verify the agreed
80 next development version. Create and read back a GitHub Release only when
81 repository conventions call for it, using the finalized release notes.
829. On partial or uncertain success, stop dependent mutations and report verified,
83 failed and unknown stages without secrets. Inspect live artifact, workflow,
84 tag and branch state before recovery; never blindly repeat publication,
85 overwrite remote tags, delete published artifacts or claim rollback. Resume
86 only a proven remaining action within existing authorization.
87
88## Finish gate
89
90Report the release version, release commit/tag, validation evidence, artifact
91readback, next development commit and conditional GitHub Release URL. Claim
92completion only when every applicable check passes. For review, preparation or
93blocked work, state that narrower outcome and the remaining gate explicitly.
94Do not expose credential contents or raw sensitive command output.