philoserf/skills/obsidian-release

Release (Obsidian Plugin)

Final step in the release pipeline. Assumes obsidian-release-check has already passed and the target version has been decided.

This skill follows the prep-PR pattern: version bump + CHANGELOG + walkthrough ship as one atomic PR. The tag is applied after merge, pointing at the merged commit. Do not use bun version or npm version with auto-tag — they tag immediately and skip the CHANGELOG/walkthrough step.

Prerequisites

Before starting, confirm:

• obsidian-release-check passed with no FAIL status
• Working tree is clean and on main
• Target version decided
• Target version is not already tagged (git tag -l <version>)

If any prerequisite is unclear, ask rather than proceeding.

Workflow

Phase 1: Prep Branch

Create a feature branch off main:

git checkout -b release/<version>

Phase 2: Version Bump

Edit package.json directly (do not run npm version / bun version — they auto-tag):

1. Edit the version field in package.json to <version>.

2. Sync manifest.json and versions.json by running the version script with the env var:

   npm_package_version=<version> bun run version
   

   (version is the package.json script that invokes version-bump.ts.)

3. Verify all three files agree:

   jq -r '.version' package.json
   jq -r '.version' manifest.json
   jq -r 'keys[-1]' versions.json
   

   If they don't match, stop and surface the discrepancy.

Phase 3: CHANGELOG

Add a ## <version> section to CHANGELOG.md above the previous version entry. Draft the entry from git log <last-tag>..HEAD and present to the user for review before committing.

Phase 4: Walkthrough

If walkthrough.md exists, regenerate it via the walkthrough skill so code blocks reflect the release state.

Phase 5: Commit and Open PR

One atomic commit for the whole prep:

git add package.json manifest.json versions.json CHANGELOG.md
[ -f walkthrough.md ] && git add walkthrough.md
git commit -m "chore: prepare release <version>"

Confirm with the user before pushing, then:

git push -u origin release/<version>
gh pr create --title "chore: prepare release <version>" --body "..."

Draft the PR body from the CHANGELOG entry. Stop here and wait for the PR to merge — the user reviews and merges it (possibly after CI runs and feedback).

Phase 6: Tag After Merge

Once the PR is merged, sync local main and tag the merged commit. Tags use bare version numbers (no v prefix):

git checkout main
git pull --ff-only origin main
MERGED_SHA=$(git log -1 --format=%H --grep="chore: prepare release <version>")
if [ -z "$MERGED_SHA" ]; then
  echo "Could not find the merged release commit by message."
  echo "Get the merge commit SHA from the merged PR (e.g. gh pr view <num> --json mergeCommit) and retry with that SHA."
  exit 1
fi
git tag -a <version> -m "Release <version>" "$MERGED_SHA"

Confirm with the user before pushing the tag.

Phase 7: Push Tag

git push origin <version>

The tag push triggers .github/workflows/release.yml, which builds the plugin and creates a GitHub release whose assets are whatever that workflow's files: block lists. Common combinations: main.js + manifest.json, or main.js + manifest.json + styles.css. Extract the actual list before producing the final output:

yq '.jobs.build.steps[] | select(.uses == "softprops/action-gh-release*") | .with.files' .github/workflows/release.yml

If yq is unavailable, grep for the files: block and read the lines that follow.

Phase 8: Update Release Notes

Wait for the release workflow to complete:

gh run list --branch main --limit 3 --json status,conclusion,name,headBranch

Check once; if still running, wait ~30 seconds and check again. If the workflow fails, report the failure and stop.

Once the release exists, extract the CHANGELOG section for this version — everything between ## <version> and the next ## heading — and update the GitHub release:

gh release edit <version> --notes "$(cat <<'EOF'
<extracted changelog content>
EOF
)"

Phase 9: Verify

Confirm the release is live and report:

gh release view <version> --json tagName,name,body,assets

Output

Release: <version>
====================
Prep PR:        #<num> (merged <sha>)
Files bumped:   package.json, manifest.json, versions.json
CHANGELOG:      ## <version> added
Walkthrough:    regenerated
Tag:            <version> → <sha>
GitHub release: <url>
Assets:         <list extracted from release.yml — e.g. main.js, manifest.json>
Release notes:  updated from CHANGELOG.md

Do not use when

• Project is not an Obsidian plugin — use language-native release tooling
• Pre-tag validation hasn't run — use obsidian-release-check first