Skip to main content
GeneralParslee-ai

source-command-prepare-release

Prepare a new release by updating versions, changelog, and building distributions

Stars
12
Source
Parslee-ai/neo
Updated
2026-05-26
Slug
Parslee-ai--neo--source-command-prepare-release
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/Parslee-ai/neo/HEAD/.agents/skills/source-command-prepare-release/SKILL.md -o .claude/skills/source-command-prepare-release.md

Drops the SKILL.md into .claude/skills/source-command-prepare-release.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

source-command-prepare-release

Use this skill when the user asks to run the migrated source command prepare-release.

Command Template

Prepare Release

Updates version numbers, CHANGELOG.md, and builds distributions for a new release.

Usage

/prepare-release 0.7.7

What This Does

  1. Validates the new version is higher than current and follows semver format
  2. Reviews commits since last release tag
  3. Updates CHANGELOG.md with new version section and categorized changes
  4. Updates version in:
    • pyproject.toml (line 7)
    • src/neo/__init__.py (line 5)
    • .claude-plugin/plugin.json
    • plugins/neo/.codex-plugin/plugin.json
  5. Syncs the local editable install metadata so importlib.metadata.version("neo-reasoner") matches the new version
  6. Builds wheel and sdist distributions
  7. Reports what was done and next steps

Workflow

Step 1: Validate

  • Read current version from pyproject.toml
  • Verify new version is higher and matches format X.Y.Z
  • Check that last git tag exists (e.g., v0.7.6)

Step 2: Analyze Commits

Run git log v{last_version}..HEAD --oneline and categorize by type:

  • Fixed: Commits with "fix:" prefix or fixing bugs
  • Added: Commits with "feat:" prefix or new features
  • Changed: Commits with "refactor:" or "perf:" or improvements
  • Documentation: Commits with "docs:" prefix

Step 3: Update CHANGELOG

Add new section at top of CHANGELOG.md:

## [{new_version}] - {today's date}

### Fixed
- List of bug fixes from commits

### Added
- List of new features from commits

### Changed
- List of improvements from commits

### Documentation
- List of doc updates from commits

Step 4: Update Versions

Update version string in all four files:

  • pyproject.toml: Change version = "X.Y.Z"
  • src/neo/__init__.py: Change __version__ = "X.Y.Z"
  • .claude-plugin/plugin.json: Change "version": "X.Y.Z"
  • plugins/neo/.codex-plugin/plugin.json: Change "version": "X.Y.Z"

Step 5: Sync Local Editable Metadata

After version files are updated, refresh the current environment's editable install metadata:

python -m pip install -e . --no-deps
python -c "import importlib.metadata as m; assert m.version('neo-reasoner') == '{new_version}', m.version('neo-reasoner')"

If the command runs in a project virtualenv, use that virtualenv's Python. This prevents neo --version or local tests from reporting the previous release after pyproject.toml was bumped.

Step 6: Build Distributions

Run:

python -m build --wheel --outdir dist/
python -m build --sdist --outdir dist/

Verify both files were created in dist/ directory.

Step 7: Report Results

Show what was updated and provide next steps:

# Next steps:
git add CHANGELOG.md pyproject.toml src/neo/__init__.py .claude-plugin/plugin.json plugins/neo/.codex-plugin/plugin.json
git commit -m "chore: bump version to {new_version}"
git tag v{new_version}
git push origin main --tags

Error Handling

  • If version format is invalid, report and stop
  • If new version isn't higher than current, report and stop
  • If git tag doesn't exist, report and stop
  • If build fails, show error and stop
  • For any failure, explain what went wrong and how to fix it

Notes

  • This command does NOT commit, tag, or push - you review first
  • Distributions are built to verify everything works
  • Use /ship-release for the full release workflow including PR creation