version-bump

name	version-bump
description	Prepare a new Xamal version locally — bump @version in mix.exs, roll the CHANGELOG.md
metadata	{"version":"1.0.0"}

Version bump

Prepare the repository for a new release locally. This skill never commits, tags, pushes, or publishes — it only edits files and verifies them. Use the release skill for the privileged steps (those need push rights / HEX_API_KEY).

Inputs

• The target version (e.g. 0.3.3). If the user didn't give one, infer from the unreleased changes and SemVer, then confirm:
  • Bug fixes only → patch (0.3.2 → 0.3.3)
  • New backwards-compatible features → minor (0.3.2 → 0.4.0)
  • Breaking changes → major (0.3.2 → 1.0.0), or minor while 0.x
• Read the current version from mix.exs (@version "...").

Steps

1. Confirm the repo is clean and current. Run git fetch and check the working tree is clean and the local branch is not behind its remote. If the remote has moved, stop and tell the user to integrate first — tagging a stale commit is the failure mode this skill exists to prevent.

2. Bump @version in mix.exs. Change only the @version "..." attribute (line ~4). Everything else (package(), docs(), source_ref) is derived from it — do not touch those.

3. Roll the changelog. In CHANGELOG.md:

   • Rename the ## [Unreleased] heading to ## [x.y.z].
   • Add a fresh empty ## [Unreleased] section above it (so contributors always have a target for the next cycle).
   • Add a tag-link line at the bottom in the existing style: [x.y.z]: https://github.com/dmkenney/xamal/releases/tag/vx.y.z
   • Keep the existing Keep-a-Changelog format (### Added/Changed/Fixed/Removed, no dates). Do not switch formats.
   • If ## [Unreleased] is empty, draft entries from git log <prev-tag>..HEAD --oneline and the PR titles, then ask the user to review them. Never invent user-facing notes for internal/CI-only commits without flagging them.

4. Verify the wiring is still correct (these are derived, not edited — confirm they didn't drift):

   • README.md install snippet uses a ~> constraint (e.g. {:xamal, "~> 0.3", ...}). It should only change on a major/minor boundary that moves the constraint, never on a patch. Leave it alone unless the new version crosses that boundary.
   • mix.exs docs() source_ref: "v#{@version}" and package() links still point at the right places (they're derived — just sanity-check).

5. Run mix ci. It must pass clean (credo, architecture policy, dialyzer 0 errors, all tests). If it fails, stop and report — do not proceed.

6. Report the two files changed (mix.exs, CHANGELOG.md), the version delta, and the changelog section that will become the release notes. Then hand off: tell the user the prep is done and the release skill (or a maintainer) handles commit → push → tag → publish.

Do not

• Do not git commit, git tag, git push, or mix hex.publish.
• Do not edit package()/docs() directly or add a maintainers: field (Hex uses package owners via mix hex.owner, not the deprecated field).
• Do not bump the README ~> constraint on a patch release.