| name | ship |
| description | Release workflow for the notion-markdown-sync plugin. Analyzes changes, drafts changelog entry, bumps version, commits, tags, pushes, and creates a GitHub release. Use when the user says "ship", "release", or "cut a release".
|
Ship — Release Workflow
Automate the full release cycle for the notion-markdown-sync plugin.
Step 1: Analyze the Diff
Run these commands to understand what changed:
git diff --stat
git diff
git status
git log --oneline -10
Read the current version from .claude-plugin/marketplace.json (plugins[0].version).
Read the first entry in CHANGELOG.md for format reference.
Summarize: what changed, which files, what's the impact.
Step 2: Draft Changelog + Version
Suggest a version bump based on scope:
- Patch (x.y.Z): bug fixes, doc corrections, minor tweaks
- Minor (x.Y.0): new features, new GFM conversions, new property types supported
- Major (X.0.0): NEVER auto-suggest. Only if user explicitly requests.
Draft a changelog entry in Keep a Changelog format:
## [X.Y.Z] - YYYY-MM-DD
One-line summary.
### Added / Changed / Fixed / Removed
- Bullet points describing each change
Draft a commit message:
chore: release vX.Y.Z
<one-line summary of what this release includes>
Draft GitHub release:
- Title:
vX.Y.Z — Short Description
- Body:
## What's New
- Bullet points of user-facing changes
## Files Changed
| File | Change |
|------|--------|
| `path/to/file` | Description |
---
Full changelog: [CHANGELOG.md](CHANGELOG.md)
Present all drafts to the user. Wait for confirmation before proceeding.
Step 3: Apply Version Bump
After user confirms:
- Prepend the new changelog entry to
CHANGELOG.md (after the header, before the previous version)
- Update version in
.claude-plugin/marketplace.json → plugins[0].version
- Do NOT update version in
plugin.json (marketplace.json is the authority)
Step 4: Wait for Push Confirmation
Show a summary of all changes and ask: "Ready to push and create the release?"
Do NOT proceed until the user explicitly says to push.
Step 5: Execute Ship
- Stage specific files:
git add <file1> <file2> ... — never use git add -A or git add .
- Commit with the approved message (use HEREDOC format)
- Create annotated tag:
git tag -a vX.Y.Z -m "vX.Y.Z: <summary>"
- Pull with rebase:
git pull --rebase
- Push commits and tag:
git push && git push --tags
- Create GitHub release:
gh release create vX.Y.Z --title "vX.Y.Z — <title>" --notes "$(cat <<'EOF'
<release body>
EOF
)"
- Print the release URL
Rules
- NEVER commit or push without explicit user confirmation
- NEVER use
git add -A or git add . — always stage specific files
- NEVER force-push
- Always
git pull --rebase before push
- If push fails, diagnose the issue — don't retry blindly
- Changelog entries are prepended, never modify existing entries
- Version lives ONLY in
marketplace.json — nowhere else
