iru-release

Convert the current development version into a final release. Must be run from the `develop` branch (gitflow) — warns and stops otherwise. Detects the repository's ecosystem (Java/Kotlin JVM on Maven

SKILL.md

GitHub

Release

Turn the current development version into a release: pick the version numbers, cut a release_x.y.z branch, update every place that names the current release/pre-release version, draft the "what's new" notes, and open a pull request. This mirrors the repository's existing release history (release_1.0.0 … release_1.3.0, each a PR into main) — follow that convention unless the user says otherwise.

Step 1 — Verify this is being run from develop

This is a precondition and must be checked before anything else in this skill, including reading versions or touching any file.

  • Run git branch --show-current.
  • If it is not exactly develop, stop immediately: warn the user that this skill follows gitflow and must be run from the develop branch, tell them which branch they're actually on, and ask them to git checkout develop (pulling/updating it first if needed) and re-invoke /iru-release. Do not proceed to any later step, do not offer to branch from the current branch instead, and do not read or modify any file first.
  • Only continue to Step 2 once the current branch is confirmed to be develop.

Step 2 — Detect the ecosystem and gather the current version

  • Detect the ecosystem. Reuse iru-explore's result rather than re-deriving it — the manifest check in 2. is only a fallback for when no exploration is available:
    1. If iru-explore ran earlier in this conversation, read its ## Tech stack report's - Project type: line (see .claude/skills/iru-explore/SKILL.md for the exact vocabulary — java-library, java-springboot, java-springboot-hilla, typescript-library, react-web, angular-web, android-library, android-app, swift-library, apple-app, etc.) and derive the ecosystem key from it: java-*/kotlin-* (java-library, java-springboot, java-springboot-hilla, kotlin-springboot, kotlin-springboot-hilla, java-quarkus, kotlin-quarkus — Maven or Gradle) → java; typescript-library/react-web/angular-web/nestjs/nextjs/ionic-app → typescript; react-native-app (expo|metro) → react-native (its bump skill owns package.json plus the store-facing version — app.json's expo.version for Expo, android/app/build.gradle + the iOS MARKETING_VERSION for Metro; fall back to typescript only when iru-react-native-bump-version isn't installed, and then warn that the store-facing version must be updated by hand); android-* → android; kmp-app (…) → kmp (fall back to android only when iru-kmp-bump-version isn't installed, and warn that the iOS MARKETING_VERSION must be updated by hand); swift-*/apple-app/macos-app → swift; windows-app (…)/dotnet → dotnet (its bump skill owns Directory.Build.props' <Version> plus the four-part MSIX Identity Version in Package.appxmanifest/packaging/AppxManifest.xml); php-* → php; python-* (python-fastapi, python-django, python-library) → python; cli-tool (rust)/rust → rust; cli-tool (go)/go → go; cli-tool (swift) → swift (its bump skill owns the CLI's Version.swift literal); cli-tool (dotnet) → dotnet. If the Project type: line is multiple, ask the user which module this release targets, since a single release cuts one version.
    2. Otherwise, detect it directly from manifests present at the repository root: pom.xml → java; package.json with react-native or expo in its dependencies (an app) → react-native; any other package.json — including a React Native library, which lists react-native only in peerDependencies/devDependencies — → typescript; a Gradle build applying the Kotlin Multiplatform plugin (kotlin("multiplatform") / org.jetbrains.kotlin.multiplatform) with iOS targets → kmp; build.gradle/build.gradle.kts with the Android Gradle Plugin applied → android; build.gradle/build.gradle.kts without it (a plain JVM, Kotlin Spring Boot, or Quarkus Gradle build) → java; Package.swift, or a *.xcodeproj/project.yml/Project.swift → swift; composer.json, a WordPress plugin/theme header (Plugin Name: in the main PHP file, Theme Name: in style.css), or a PrestaShop module main class (extends Module) → php; pyproject.toml (or setup.py/setup.cfg) → python; a *.slnx/*.sln, Directory.Build.props or *.csproj → dotnet; Cargo.toml → rust; go.mod → go. Ask the user which one this release targets if more than one manifest is found and it's genuinely ambiguous which is the release target.
  • Find the installed bump-version skill for that ecosystem:
    find .claude/skills -maxdepth 1 -type d -name "iru-*-bump-version"
    
    The key is each matching directory's name with the iru- prefix and -bump-version suffix stripped (e.g. iru-java-bump-version → java). Match the detected ecosystem's key against what's actually installed.
    • Match found: read that skill's own SKILL.md and apply its documented "read the current version" mechanism directly to obtain the current value — every iru-<key>-bump-version skill in this catalog documents locating and reading the current version as the very first thing it does before writing anything (e.g. iru-java-bump-version's Step 3 locates the project's own pom.xml <version>, or for a Gradle build lists every gradle.properties/build.gradle(.kts)/libs.versions.toml version location; iru-typescript-bump-version's Step 3 reads package.json's version field; iru-android-bump-version's Step 3 reads lib/build.gradle.kts's libraryVersion; iru-react-native-bump-version reads package.json's version; iru-kmp-bump-version reads the root gradle.properties' VERSION_NAME; iru-dotnet-bump-version reads Directory.Build.props' <Version> (or each project's own); iru-swift-bump-version's Step 5/"Library" case reads the latest git tag; iru-python-bump-version reads pyproject.toml's [project].version; iru-rust-bump-version reads Cargo.toml's [package].version (or [workspace.package].version); iru-go-bump-version reads the Version literal in internal/version/version.go) — none of these skills expose a separate read-only invocation mode, reading is simply their first ordinary step, so apply that same locate-and-read logic here rather than inventing a different one. Also read that skill's own dedicated pre-release-convention section (iru-java-bump-version's Step 5, iru-typescript-bump-version's Step 5, iru-android-bump-version's Step 5, iru-swift-bump-version's Step 5, and the equivalent pre-release-convention section of iru-react-native-bump-version/iru-kmp-bump-version/iru-php-bump-version/iru-python-bump-version/iru-dotnet-bump-version/iru-rust-bump-version/iru-go-bump-version) to know this ecosystem's convention for the rest of this skill (e.g. -SNAPSHOT for Java/Android/KMP, -dev.N for npm and React Native, -dev for PHP, .NET, Rust, Go and Swift command-line tools, PEP 440 .devN such as 1.4.0.dev0 for Python, "the release is the git tag itself, there is no in-tree pre-release marker" for a Swift library).
    • No match installed: fall back to asking the user which file carries the version (e.g. pom.xml, package.json) and what its pre-release suffix convention is — don't guess a bump-version skill into existence, and don't fall back to editing that file directly either at this point. Note in the final report (Step 12) that the version bump in Step 6 will need to be done by hand, since no matching iru-<key>-bump-version skill is installed in this repository's .claude/skills/.
  • The current version must be a pre-release per that ecosystem's convention (e.g. ends in -SNAPSHOT for Java/Android, -dev.N for npm, .devN for Python) — if it isn't, tell the user there's nothing to release and stop. This check doesn't apply the same way to a Swift library, which has no in-tree pre-release marker at all: its "current version" is simply the latest git tag (git describe --tags --abbrev=0); a Swift app's MARKETING_VERSION is likewise always a plain release-shaped string, per iru-swift-bump-version's Step 5 — for either, skip this specific check and treat the latest tag/current MARKETING_VERSION as the version to bump from. The same applies to a Python project whose version is VCS-derived (hatch-vcs, setuptools-scm — iru-python-bump-version reports "derived from git tags" and changes nothing): treat the latest tag as the version to bump from and the release tag itself as the release.
  • Find the latest released version: git tag --sort=-v:refname | head -1 (falls back to "no previous release" if there are no tags — a first release).
  • Check the working tree is clean (git status). If there are uncommitted changes, stop and ask the user to commit or stash them first — a release branch should not carry unrelated in-progress work.
  • Determine the PR's target/base branch: it must be main or master, whichever this repository actually has — never anything else. Check git ls-remote --heads origin main master (or git branch -a if offline) rather than assuming; older repositories tend to use master, newer ones main. If both somehow exist, prefer main. If neither exists, stop and ask the user which branch releases should target — don't guess. This is where the release branch's pull request will point (Step 10) — the release branch itself always originates from develop, per Step 1.

Step 3 — Ask for the release version

Compute three candidates and present them with AskUserQuestion (previews help here — show the resulting version string for each):

  • Current pre-release value stripped (e.g. Java/Android 1.4.0-SNAPSHOT → 1.4.0, npm 1.4.0-dev.0 → 1.4.0, Python 1.4.0.dev0 → 1.4.0, per the convention detected in Step 2) — recommended default; this repo's convention is to already bump the pre-release marker to the next planned minor right after the previous release, so this is normally the right one. For a Swift library, where there is no in-tree pre-release marker, this option is instead simply "the next semver bump from the latest tag" (see iru-swift-bump-version's Step 5).
  • A new patch version — latest tag with its patch component incremented (e.g. latest tag 1.3.0 → 1.3.1), for when the changes since the last release turned out to be small enough not to warrant the pre-planned minor.
  • A new major version — latest tag with its major incremented and minor/patch reset to 0 (e.g. 1.3.0 → 2.0.0), for when the changes are breaking.

AskUserQuestion always offers a free-text "Other" option too, so an arbitrary version is always possible. Treat whatever is chosen/typed as the release version for the rest of this skill; validate it looks like X.Y.Z.

Step 4 — Ask for the upcoming pre-release version

Using the release version chosen in Step 3, compute three bump candidates (minor/patch/major) for the next development version per the ecosystem's own convention detected in Step 2 (e.g. Java/Android 1.5.0-SNAPSHOT, npm 1.4.1-dev.0), and ask via AskUserQuestion which to use — default/recommended: minor bump, matching this repo's established convention (e.g. release 1.4.0 → next 1.5.0-SNAPSHOT). The chosen bump type plus the convention's pre-release suffix is the upcoming version referenced in README/docs text for the rest of this skill. This step doesn't apply the same way to a Swift library (no in-tree pre-release marker to compute a next value for) — skip it for that ecosystem and move on to Step 5.

Note for the final report (Step 12): this skill only bumps the version file(s) to the release version, in Step 6 — it does not itself bump them again to the upcoming pre-release version afterward. That second bump can happen automatically once the release is published, if this repository has a Sync GitHub workflow (.github/workflows/sync.yml — every iru-setup-<stack>-github-workflows skill in this catalog generates one, whatever the ecosystem): it opens a sync_x.y.z pull request into develop that merges the released branch back in and bumps the version file(s)/README.md/the Antora docs to the next pre-release value via the version script it ships with (e.g. .github/scripts/sync_versions.py). This is purely file-driven — check whether .github/workflows/sync.yml actually exists before relying on it, regardless of the ecosystem detected in Step 2:

  • Exists: no manual next-dev bump is needed — note in Step 12's report that the Sync workflow will handle it, and that its minor-bump default should match the upcoming version chosen here (flag it if it doesn't).
  • Doesn't exist: say so plainly in Step 12's report instead of assuming the next-dev bump will happen on its own. The user is responsible for that bump instead — typically a follow-up manual call to the same iru-<key>-bump-version skill used in Step 6, against develop, with the upcoming version computed here.

Step 5 — Create the release branch

  • Confirm release_<version> doesn't already exist locally or on origin (git branch --list, git ls-remote --heads origin release_<version>) — stop and ask the user how to proceed if it does.
  • git checkout -b release_<version> from develop (confirmed to be the current branch in Step 1).

Step 6 — Bump the version

Delegate the actual file rewrite to the bump-version skill matched in Step 2, rather than editing any build file directly:

Skill({skill: "iru-<key>-bump-version", args: "<release-version>\nsync-files: yes\nnext-version: <upcoming-version>"})

substituting the ecosystem key found in Step 2 (e.g. iru-java-bump-version, iru-typescript-bump-version, iru-android-bump-version, iru-swift-bump-version), the release version chosen in Step 3, and the upcoming pre-release version chosen in Step 4 (omit the next-version line when Step 4 didn't apply — a Swift library). Passing sync-files: yes folds what used to be this skill's own separate README/docs/antora.yml/Antora-page- snippet update steps into this single delegated call — each iru-<key>-bump-version skill's own optional sync step already covers exactly those files for its ecosystem, so there's no separate step here for them anymore. next-version is what keeps that sync from regressing the README: a README/docs page typically names both the latest release and the current development version ("Latest release" / "Latest snapshot" / "Current development version" markers, or the equivalent for the ecosystem), and the bump-version skill maps the release markers to <release-version> and the snapshot/development markers to next-version — never all of them to the single release value. Review whatever that skill reports back (old/new version, every file it touched, any warnings) before continuing to Step 7, and apply this regression guard yourself: if the installed iru-<key>-bump-version skill's Step 0 doesn't list next-version (an older copy), or its report shows a snapshot/development marker now equal to the release version, correct those specific mentions by hand so "Latest release" shows <release-version> and "Latest snapshot"/"Current development version" show <upcoming-version> — don't accept a README that regresses either fact.

If Step 2 found no matching iru-<key>-bump-version skill installed, this is the point where the user (or this skill, best-effort, only if the user explicitly asks it to proceed anyway) must edit the version file(s) by hand instead — note clearly in Step 12's report that this happened without the usual delegated skill.

The later "next development version" bump discussed in Step 4 — when it isn't handled by an automated workflow (no sync.yml) and the user wants it done as part of this same session rather than left for later — also goes through the same iru-<key>-bump-version skill: call it again with the upcoming pre-release version computed in Step 4, typically against develop once this release branch/PR exists, never against the release branch itself.

Step 7 — Determine what changed, then update whats-new.adoc and CHANGELOG.md

Both files describe the same release from the same underlying analysis — do the analysis once, then write it into each file in its own house style. Don't let them drift: same set of changes, same version, same date.

  • Gather what actually changed since the previous release: if a previous tag was found in Step 2, delegate the commit/diff reading to the iru-change-summarizer agent rather than reading git log/diffs inline — the same job iru-setup-changelog uses it for, just for a single range here instead of a fan-out across many past releases: Agent({description: "Summarize changes since <previous-tag>", subagent_type: "iru-change-summarizer", prompt: "Summarize <previous-tag>..develop for a Keep a Changelog entry. Source directories for this repository: (the library's main source, excluding repository tooling/CI/editor-assistant config). Report back only a short bullet list of user-facing changes, grouped by Added/Changed/Deprecated/Removed/Fixed/Security where applicable."}). Use the returned bullet list as the basis for both files below. If there is no previous tag, this is the first release — write a short section describing the library's initial capabilities instead of a diff-based changelog (no agent call needed, there's no range to summarize).
  • docs/modules/ROOT/pages/whats-new.adoc: check whether it already exists. Compose a new, brief section for the release version being cut (heading + short bullet list, one line per change, emojis optional per this repo's existing README style — e.g. ✨ for new features, 🐛 for fixes, ♻️ for behavioral changes). Insert it at the top of the page (newest first) above any existing sections — don't rewrite or drop prior sections. If the page doesn't exist yet, create it following this module's conventions (see index.adoc for the house style: a = Title heading and, since this page's content is being drafted by this skill, the same AI-assistance disclaimer note index.adoc already carries), and add an xref:whats-new.adoc[] entry to docs/modules/ROOT/nav.adoc, placed right after xref:index.adoc[] so it's the first thing a reader sees after the overview.
  • CHANGELOG.md (repository root): follows Keep a Changelog — an ## [Unreleased] section always sits at the top, followed by one ## [<version>] - <YYYY-MM-DD> section per release, newest first, each with ### Added/### Changed/### Fixed/### Removed subsections as applicable (omit empty subsections). Rename ## [Unreleased] to ## [<release-version>] - <today's date> using the same change list just composed for whats-new.adoc (same substance, terser Keep a Changelog wording — no need to match sentence-for-sentence), then add a fresh empty ## [Unreleased] section above it. Update the compare links at the bottom of the file: retarget the [Unreleased] link to compare/<release-version>...HEAD and add a new [<release-version>]: compare/<previous-tag>...<release-version> link (or releases/tag/<release-version> if there's no previous tag). If CHANGELOG.md doesn't exist yet, create it with this same structure, an [Unreleased] section, and one entry for the release being cut.

Step 8 — Review, then commit

Show the user a summary of every file changed (git status, git diff --stat) before committing. Commit with a message matching this repo's convention: Release <version> (see git log --oneline on the previous release branches for the exact style).

Step 9 — Confirm before pushing and opening the PR

Pushing a branch and opening a pull request are visible, shared-state actions — confirm with the user before proceeding, summarizing: the branch name, the release version, the upcoming pre-release version (if Step 4 applied to this ecosystem), the target base branch, and the files changed. Only continue once they say to go ahead.

Step 10 — Push and open the pull request

  • git push -u origin release_<version>.
  • Determine which platform hosts this repository, the same way iru-pr-description's Step 1 does: reuse the Repository host: ... line from an iru-explore report already in this conversation if one exists; otherwise detect it directly from git remote get-url origin (falling back to git remote -v) against known patterns — github.com (or a GitHub Enterprise Server domain) → GitHub; bitbucket.org (cloud), or a self-hosted /scm/<project>/<repo>.git path (Server/Data Center) → Bitbucket; dev.azure.com/<org>.visualstudio.com → Azure DevOps (cloud); a self-hosted /tfs/ path segment, or bare _git without a dev.azure.com/visualstudio.com domain → Azure DevOps Server / TFS. Ask the user (AskUserQuestion) if the URL doesn't clearly match any of these.
  • Ensure a release label/tag exists and open the PR, using the tool matching the detected host:
    • GitHub: ensure a release label exists (gh label list — create it with gh label create release --description "Release pull request" --color <any hex> if it's missing), then:
      gh pr create --base <main-or-master> --head release_<version> --title "Release <version>" \
        --body "Release <version>." --label release
      
      If gh pr create for some reason doesn't accept --label (older gh versions), fall back to gh pr edit <number> --add-label release immediately after creating it — the PR must not be left without the label.
    • Bitbucket: open the pull request via Bitbucket MCP tools if connected (ToolSearch "bitbucket"), otherwise the REST API (POST /2.0/repositories/<workspace>/<repo>/pullrequests for Cloud, or the Server/Data Center equivalent), titled Release <version>, from release_<version> into <main-or-master>. Bitbucket pull requests don't carry GitHub-style labels — if this repository's Bitbucket project exposes its own tag/label tooling, add an equivalent release tag there; otherwise note in Step 12's report that no label/tag was attached because the host doesn't support one the same way GitHub does.
    • Azure DevOps / TFS: az repos pr create --target-branch <main-or-master> --source-branch release_<version> --title "Release <version>" --description "Release <version>.", or Azure DevOps MCP tools if connected (ToolSearch "azure devops"). Add the equivalent label via az repos pr update --id <id> --labels release if the installed CLI/extension version supports PR labels; otherwise note it the same way as the Bitbucket case.
    • If no tool for the detected host is available at all (no CLI installed/authenticated and no matching MCP connection), tell the user and stop here — Step 11 needs an actual pull request to attach its description to.
  • Open the PR against the main/master branch determined in Step 2 — never develop or any other branch.

Step 11 — Fill in the PR description

Invoke Skill({skill: "iru-pr-description", args: "base-branch: <main-or-master>"}), passing the release PR's target branch resolved in Step 2 so the description is drafted against the same base the PR targets rather than whatever the repository's default branch happens to be. It will find the PR just opened in Step 10 (same branch), detect the same repository host itself, draft a description from the actual diff, show it, and — once confirmed — update the PR body using that host's own tooling.

Step 12 — Report

Summarize: the ecosystem detected in Step 2 and which iru-<key>-bump-version skill was used (or, if none was installed, that the bump was done by hand); the release version and upcoming pre-release version chosen (or "not applicable — Swift library" per Step 4); the branch and PR URL; the repository host the PR was opened on; which files were updated (per Step 6's delegated skill report, plus the changelog files from Step 7); and what was written to whats-new.adoc and CHANGELOG.md.

Remind the user, per Step 4's finding: if .github/workflows/sync.yml exists, that once this PR is merged and a release is published from it, the Sync workflow will automatically open a follow-up PR into develop bumping the development version (no manual sync step is needed unless that workflow's minor-bump default doesn't match the upcoming version chosen in Step 4); if it doesn't exist, state plainly that no such automation ran and the next-development-version bump — if wanted now — is a manual follow-up call to the same iru-<key>-bump-version skill used in Step 6, against develop.