Update Version Catalog

Update Version Catalog

Renovate is the source of version updates: it keeps each dependency bump on its own remote branch origin/renovate/<dep> (e.g. origin/renovate/dagger, origin/renovate/compose-bom), with a commit topic like stack: dagger 2.60. This skill does NOT invent versions — it collects Renovate's bumps onto a fresh working branch, documents them in CHANGELOG.md, and validates the catalogs.

This document is self-contained: all CHANGELOG.md formatting rules are inlined below. Everything that can be checked mechanically IS checked mechanically — lint-changelog.sh, check-doc-links.sh and finish-check.sh are the source of truth, not your own reading of the diff.

HARD RULE — respond in Russian

All output shown to the user — progress updates, questions, summaries, and the final report — MUST be written strictly in Russian, regardless of the language of the user's request. This applies only to the assistant's messages; code, commit messages, CHANGELOG.md entries, and file contents follow their own existing conventions and are unaffected.

HARD RULE — work only on the created branch

All work happens on the single dev-update-YYYY-MM-DD branch created in step 1.

• NEVER commit, amend, reset, rebase, cherry-pick, push, or otherwise mutate any other branch — especially main. main may only be read (fetched / pulled fast-forward in step 1) and used as the cherry-pick/reset base.
• Confirm you are on the working branch before every commit/amend/reset (git branch --show-current → must be dev-update-*). If it is not, STOP and fix the branch before running the command.
• Do NOT touch release/* or origin/renovate/* branches (renovate branches are read-only sources for cherry-pick).
• Do NOT git push anything unless I explicitly ask.

If any step would require changing a branch other than the working one, STOP and ask me instead of proceeding.

Command types — recognise what was asked before starting

Every command is one of three kinds:

All additions requested by one command share a single addition commit, no matter how many dependencies are added. A correction to an earlier result («исправь ссылку», «поправь changelog») is none of these — it is a continuation of the previous command (see workflow step 1) and creates no new commit.

Before doing ANYTHING else, classify the command against this table and tell the user (in Russian) which kind it is. For a Both at once command, explicitly announce the plan as two numbered operations — e.g. «Команда двойная: 1) обновление каталогов, 2) добавление <deps>. Начинаю с обновления.» — and track both as separate items in your task list so neither can be dropped.

HARD RULE — "Both at once" is TWO sequential operations, never one

A command that both updates and adds (any phrasing that combines them: «обнови зависимости и добавь X», «сделай обновление и добавь X», "update the catalogs and add X", or an addition mentioned anywhere in an update request) is NOT one task. It is TWO complete, sequential operations:

1. Operation 1 — Update: workflow steps 1–9, all the way through validation, producing the update commit.
2. Operation 2 — Addition: the ENTIRE "Adding a new dependency" flow (its steps 2–7; step 1 is skipped — the branch already exists), producing a SECOND, separate commit on top of the update commit.

Finishing operation 1 does NOT complete the command. Do NOT report results, do NOT stop, do NOT wait for further input after the update — continue straight into operation 2. The command is complete ONLY when finish-check.sh --expect-commits 2 passes, i.e. git log origin/main..HEAD shows BOTH commits (update + addition) and both passed validation. If you are about to write the final summary and the user's request mentioned adding a dependency but there is no addition commit — you are not done; go back and perform operation 2.

Commit rules — one command, which commits

• Update and addition are separate commits. When a single command asks both to update dependencies AND to add new ones ("обнови зависимости и добавь <deps>") — the "Both at once" row of the command-types table — produce two commits: first the update commit (all cherry-picked bumps + their CHANGELOG.md entries), then the addition commit (catalog edits + their CHANGELOG.md entries). Each commit follows the same rules — changelog folded into its own commit, lint, link checks, validation. Never mix bumps and additions in one commit.
• Never amend or rewrite commits that existed before the current command. Amending is allowed only for a commit created while executing the current command (e.g. folding CHANGELOG.md or lint fixes into it). If the dev-update-* branch already exists and carries commits from an earlier command or session, record the current command's result as new commit(s) on top — do not amend, reset, or squash into the old ones.
• These rules are enforced by the scripts, not by your memory: start-update.sh records the command base and never moves it silently; squash-commit.sh and commit-release.sh refuse to rewrite commits at or below it; commit-release.sh also refuses to create a second message-commit in the same command (a rephrased message would otherwise duplicate the addition commit). If a script refuses, read its message — do not work around it with hand-written git commands.

Catalog distribution rule

Which catalog a dependency belongs to is decided by its Maven group alone — never by product name, ecosystem, or vendor. Apply the first matching rule:

Explicit consequences (do NOT ask about these — the rule already decides):

• org.jetbrains.compose.* (Compose Multiplatform), org.jetbrains.androidx.* (multiplatform ports of AndroidX libraries), org.jetbrains.kotlin*, org.jetbrains.kotlinx.*, org.jetbrains.dokka.* → versions-stack. "Compose" or "androidx" in the name does not move a JetBrains group into versions-androidx.
• com.google.android.material (Material Components), com.google.*, com.squareup.*, Firebase, Dagger, testing frameworks, Gradle plugins → versions-stack.
• Android testing libraries in the androidx.test.* group → versions-androidx (group starts with androidx.).
• Gradle plugins follow the same rule by their plugin id / marker group: org.jetbrains.*, dev.*, com.* etc. → versions-stack unless the id starts with androidx. or com.redmadrobot..

If a dependency genuinely does not fit (e.g. a new red_mad_robot group that is not com.redmadrobot.*), STOP and ask — do not guess a catalog.

Workflow

All git operations use the ready-made scripts in .claude/skills/update-version-catalog/scripts/ — do NOT hand-write git commands, run these instead (via the Bash tool / Git Bash). Every mutating script guards that HEAD is a dev-update-* branch, uses origin/main only as a read-only base, and never opens an editor (so nothing can hang the session).

The scripts run on macOS and Windows/Git Bash alike: they stay within bash 3.2 (the version macOS ships) and POSIX/BSD tool behaviour. When editing them, keep to the rules documented at the top of lib.sh — no associative arrays, no ${var,,}, no sort -V (use vsort/vge), no \t/\n in a sed replacement, no \s in a regex, and no expansion of a possibly-empty "${array[@]}". *.sh is pinned to LF in .gitattributes: a CRLF copy would fail on macOS with $'\r': command not found.

1. Fetch and create the working branch — run at the start of EVERY command

First check where you are: git branch --show-current.

• On main or already on a dev-update-* branch → run:

  bash .claude/skills/update-version-catalog/scripts/start-update.sh

  The script ALWAYS starts by fetching all remote branches with an explicit refspec, so the fresh origin/main and every current origin/renovate/* branch are available BEFORE the working branch is created. On main it then creates dev-update-YYYY-MM-DD (today's date) off the freshly fetched origin/main; local main is never modified. Pass an explicit YYYY-MM-DD to override the date. Already on a dev-update-* branch it stays there — the current command's results become new commit(s) on this branch.

  It also refuses to start from any other branch and with a dirty working tree (uncommitted changes would be swept into the release commit by commit-release.sh). If it refuses, report the message and ask me — do not pass --force on your own.

• On any other branch (release/*, feature branch, …) → STOP and ask me which branch to work on; do not guess.

Command base. The script records the current HEAD as the command base; squash-commit.sh / commit-release.sh never rewrite anything at or below it. Run it exactly once per command, at the start. If it is run again while a command is in progress it now keeps the recorded base and prints a NOTE — that is the safe behaviour, not an error. Only a genuinely NEW command on a branch that already carries commits should move the base, with start-update.sh --new-command.

What counts as a command. A command is a user request that starts a NEW update or addition task («обнови каталоги», «добавь зависимость …»). A follow-up request that corrects the result already produced in this session («исправь ссылку», «поправь changelog», fixing a lint/link problem you reported) is a continuation of the previous command, NOT a new command: do NOT re-run start-update.sh for it. Just edit the files and re-amend with commit-release.sh.

2. Cherry-pick the Renovate bumps

First review what is available, then cherry-pick:

bash .claude/skills/update-version-catalog/scripts/list-renovate-updates.sh
bash .claude/skills/update-version-catalog/scripts/cherry-pick-renovate.sh          # all
# or a subset: ... cherry-pick-renovate.sh dagger kotest hilt

Cherry-pick every renovate branch that has a new commit — not only the ones touching versions-*/libs.versions.toml. Infrastructure updates such as the Gradle wrapper (gradle/wrapper/*) and GitHub Actions (.github/workflows/*) belong in the release commit too; they just do NOT get a CHANGELOG.md entry (see "What NOT to record"). Skip a branch only if I explicitly say so — mention what you skipped.

On a conflict the script stops and prints exactly what to do: resolve it in versions-*/libs.versions.toml by keeping the newer version, git add the file, run GIT_EDITOR=true git cherry-pick --continue, then simply re-run the script — commits already on the branch are skipped by patch-id and by subject, and a pick that turns out empty is skipped automatically.

3. Squash the cherry-picked commits into one

All bumps collected by the current command must live in a single commit — the CHANGELOG.md changes are added to that same commit later (step 8).

bash .claude/skills/update-version-catalog/scripts/squash-commit.sh

The script builds the commit message itself (the subjects of the squashed commits, oldest first, one per line — the same style as existing release commits on main). Do NOT pass a message argument unless I explicitly asked for a specific one.

After this, on a fresh branch git log origin/main..HEAD shows exactly one commit. If the branch already carried commits from an earlier command, only the current command's commits are squashed (the script says where it stopped).

4. Extract old → new versions per catalog

bash .claude/skills/update-version-catalog/scripts/show-version-diffs.sh

From the output, collect per changed libs.versions.toml: library/plugin name, old version (- lines), new version (+ lines). Classify each as added / updated / removed / renamed (see symbols below).

Version-format change. The script's === version format guard === section decides this for you: every FORMAT_CHANGE <alias> <old> → <new> (<reason>) line is a bump whose version shape changed (pre-release suffix appeared or disappeared, semver → calendar, plain → dash-compound, segment count changed without shared leading segments). For each such line STOP and ask me to confirm, showing the library with its old → new version; continue only after I confirm. When the section prints OK — no version-format changes, do not ask about version formats at all. (Gaining or losing a plain trailing patch segment, 2.60 → 2.60.1, is not a format change and is never flagged.)

5. Categorize by section

The catalog (and its changelog subsection) is determined by the catalog distribution rule above — the subsection always matches the libs.versions.toml the change lives in: versions-androidx/ → AndroidX, versions-stack/ → Stack, versions-redmadrobot/ → red_mad_robot.

6. Add release-notes links

Every entry's library name is a link to release notes for that exact version. Where the URL comes from, in this order:

1. A previous release section of CHANGELOG.md already links this library → reuse that URL with the new version substituted. This is the default for :arrow_up: entries and almost always works.

2. Templates for the big families:

   • AndroidX: https://developer.android.com/jetpack/androidx/releases/{library}#{version} (some libraries anchor as #{library}-{version} — the anchor check in step 9 catches a wrong one);
   • GitHub projects: https://github.com/{org}/{repo}/releases/tag/{tag} — the tag format varies per project (v1.2.3, dagger-2.60.1, r6.1.1, plain 6.14.0), so do not assume the v prefix.

3. Resolve it with the script — mandatory for :sparkle: entries and for anything you are unsure about. Never construct a URL from a naming pattern:

   bash .claude/skills/update-version-catalog/scripts/resolve-doc-url.sh <group:artifact> <version>

   It checks known-doc-urls.tsv first, then reads the artifact's HomePage from its POM (Google Maven / Maven Central / Plugin Portal) and, when that is GitHub, finds the tag matching the version via git ls-remote (no API rate limit). Verdicts:

   • KNOWN <url> — from known-doc-urls.tsv; use as-is.
   • RELEASE <url> / TAG <url> — the release/tag page for the version; use it directly.
   • HOMEPAGE <url> — only a project/repo home was found. This does NOT point at the version, so it is not a valid CHANGELOG link: show me this URL as the closest match and ask me for the correct version-specific URL. Proceed only after I supply one (or confirm the shown one).
   • NO_HOMEPAGE — the POM has no usable <url>/<scm> (common for Gradle plugin markers). Use the Plugin Portal route in "Adding a new dependency" step 5, or search GitHub for group:artifact.
   • NOT_FOUND — the artifact POM is in no repository; STOP and ask me for the URL.
   • GH_RATE_LIMITED <repo-url> — only from the API fallback; set GITHUB_TOKEN/GH_TOKEN (or wait) and re-run. It is NOT "no release exists" — do not downgrade to HOMEPAGE.

A documentation link MUST point at the specific version (path, tag or #anchor). A repository home, a docs landing page or a release-notes index without a version anchor is invalid. A Maven artifact/repository page is FORBIDDEN as an entry URL: never mvnrepository.com, search.maven.org, central.sonatype.com, maven.google.com, repo1.maven.org or similar listings. check-doc-links.sh enforces both rules in step 9.

Vendors without per-version pages. A few vendors (AppsFlyer, Firebase, Google Play services, …) publish one release-notes page for everything, or render the recent entries with JavaScript. They are listed in known-doc-urls.tsv together with the checks to skip — resolve-doc-url.sh returns their URL as KNOWN and check-doc-links.sh relaxes the version/anchor checks for them. If step 9 fails for a NEW such vendor and you have verified in a browser that the page really is the right release-notes page, propose adding a row to known-doc-urls.tsv (and say so in the report) instead of silently recording a version-less link.

7. Write entries into [Unreleased]

1. Open CHANGELOG.md, locate the ## [Unreleased] section.
2. Add each entry to the correct subsection (red_mad_robot / AndroidX / Stack).
3. Format each entry per the reference at the end of this document.
4. Sort within each subsection: regular libraries alphabetically first, then plugin: entries alphabetically.
5. Replace *No changes* when adding the first entry to a subsection; keep all three subsections present even if some stay *No changes*.
6. One entry per catalog alias that changed — an entry with the same versions as another library does not document it (lint-changelog.sh matches by alias name, not by version pair).

8. Fold CHANGELOG.md into the single commit

The CHANGELOG.md edit must go into the same commit as the version bumps — do NOT create a separate commit for the changelog alone:

bash .claude/skills/update-version-catalog/scripts/commit-release.sh

The script stages CHANGELOG.md plus any catalog edits and amends the squashed commit from step 3 (or creates the release commit when none exists yet — see "Adding a new dependency"). It prints git show HEAD --stat, which should list both the versions-*/libs.versions.toml changes and CHANGELOG.md in one commit, and warns about any modified file that was left out — read that warning, it means something is not in the commit.

Run this BEFORE the checks in step 9: they read the commit, not the working tree (lint-changelog.sh stops with an explicit message if you forget).