version-bump
Manage semantic version updates for any project. Handles patch, minor, and major version increments following semantic versioning. Updates all version-tracked files (e.g., package.json, pyproject.toml, etc.). Creates git tags and GitHub releases. Auto-generates CHANGELOG.md from releases.
When & Why to Use This Skill
This Claude skill automates the semantic versioning and release management process for software projects. It handles version increments (patch, minor, major) across various configuration files, manages Git tags, and streamlines GitHub release creation to ensure consistent, error-free, and professional software deployment cycles.
Use Cases
- Automating version bumps in macOS applications by updating Info.plist fields (CFBundleShortVersionString and CFBundleVersion) to ensure compatibility with Sparkle update detection.
- Streamlining the release workflow by automatically generating CHANGELOG.md files and creating GitHub releases with synchronized tags and release notes.
- Maintaining version consistency across multiple project metadata files such as package.json, pyproject.toml, or Info.plist during the preparation of a new release.
- Triggering CI/CD pipelines and GitHub Actions workflows by programmatically incrementing version numbers and pushing release-ready tags to remote repositories.
| name | version-bump |
|---|---|
| description | Increment app version numbers. Use when user asks to bump version, increment version, or prepare a release. |
Version Bump
Action
When this skill is invoked:
- Read current version from
mac-app/macos-host/Info.plist - Increment CFBundleShortVersionString (bump the last number, e.g.,
0.2.0-alpha.10→0.2.0-alpha.11) - Increment CFBundleVersion build number (e.g.,
11→12) - Apply the changes to Info.plist
- Report the version change to the user
Single Source of Truth
All version information comes from:
mac-app/macos-host/Info.plist
Two version fields:
- CFBundleShortVersionString: Display version (e.g.,
0.2.0-alpha.4) - CFBundleVersion: Build number (e.g.,
5) - must be incremented for every release
How to Update Version
- Edit
mac-app/macos-host/Info.plist - Update both fields:
<key>CFBundleShortVersionString</key>
<string>0.2.0-alpha.5</string>
<key>CFBundleVersion</key>
<string>6</string>
Important: Always increment CFBundleVersion. Sparkle uses this numeric value to determine if an update is available.
Version Format
Follow semantic versioning with optional pre-release identifiers:
MAJOR.MINOR.PATCHfor stable releases (e.g.,1.0.0)MAJOR.MINOR.PATCH-alpha.Nfor alpha releases (e.g.,0.2.0-alpha.4)MAJOR.MINOR.PATCH-beta.Nfor beta releases (e.g.,0.2.0-beta.1)
Release Process
- Update version in
Info.plist(both fields) - Commit the change
- Push to main
- Go to GitHub Actions and manually trigger the "Release macOS App" workflow
- The workflow will:
- Read version from Info.plist
- Build and sign the app
- Notarize with Apple
- Create GitHub release with tag
v{version} - Update the appcast at releases.nomendex.com
Where Version is Used
| Location | Source | Purpose |
|---|---|---|
| Info.plist | Manual edit | Single source of truth |
| GitHub Release | Workflow reads Info.plist | Release tag and assets |
| Appcast XML | Workflow reads Info.plist | Sparkle update detection |
| UI Sidebar | /api/version endpoint |
Display to user |
API Endpoint
The sidecar serves version info at /api/version:
{
"version": "0.2.0-alpha.4",
"buildNumber": "5"
}
This reads from Info.plist at runtime, checking multiple paths for dev vs bundled app.
Sparkle Update Detection
Sparkle compares CFBundleVersion (build number) to determine updates:
- Current app: build
5 - Appcast shows: build
6 - Result: Update available
This is why CFBundleVersion must always increase, even for the same display version.