release

roomi-fields's avatarfrom roomi-fields

Automates the complete release process for this Obsidian plugin. This skill should be used when the user requests to publish a new version, bump version numbers, sync versions across files, update changelog, build, tag, and publish to GitHub.

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 28, 2025
[CI and CD]

When & Why to Use This Skill

This Claude skill automates the end-to-end release workflow for Obsidian plugins, streamlining version management, changelog updates, and GitHub deployments. It ensures consistency across project files like package.json and manifest.json while handling technical tasks such as git tagging and asset uploads to minimize manual errors during the publishing process.

Use Cases

  • Automating version synchronization: Simultaneously updating version numbers in package.json, manifest.json, and versions.json to maintain project integrity.
  • Changelog management: Automatically formatting and inserting new release notes into CHANGELOG.md to keep users informed of updates.
  • GitHub Release automation: Using the GitHub CLI to create official releases, upload compiled assets (main.js, manifest.json, styles.css), and manage git tags.
  • Pre-deployment validation: Executing build and test scripts to ensure the plugin is stable before pushing code to the production branch.
namerelease
descriptionAutomates the complete release process for this Obsidian plugin. This skill should be used when the user requests to publish a new version, bump version numbers, sync versions across files, update changelog, build, tag, and publish to GitHub.

Release Management Skill - Obsidian Plugin

Overview

This skill automates the complete release workflow for this Obsidian plugin, ensuring consistent versioning, changelog updates, and proper publication to GitHub.

IMPORTANT: This project uses manual releases (not automated CI). The GitHub Actions release workflow is disabled to avoid conflicts.

Project Structure

Files that need version updates:

  • package.json - Source of truth for version (ALWAYS update first)
  • manifest.json - Obsidian plugin manifest (MUST match package.json)
  • versions.json - Obsidian version compatibility mapping
  • CHANGELOG.md - Release history

Pre-Release Checklist

Before starting a release:

  1. Ensure all tests pass: npm test
  2. Ensure build succeeds: npm run build
  3. Ensure working directory is clean: git status
  4. Ensure you're on the master branch: git branch --show-current

Release Workflow

1. Determine Version Bump

Follow semantic versioning (SemVer):

  • MAJOR (x.0.0): Breaking changes, incompatible API changes
  • MINOR (0.x.0): New features, backward compatible
  • PATCH (0.0.x): Bug fixes, backward compatible

2. Update Versions

Update version in ALL these files:

  • package.json
  • manifest.json
  • versions.json (add new entry if minAppVersion changes)

3. Update CHANGELOG.md

Add a new section at the top:

## [X.Y.Z] - YYYY-MM-DD

### Added

- New features

### Changed

- Changes in existing functionality

### Fixed

- Bug fixes

4. Build and Test

npm run build
npm test

5. Commit and Tag

git add -A
git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z -m "Release vX.Y.Z"

6. Push to GitHub

git push origin master
git push origin vX.Y.Z

7. Create GitHub Release (MANUAL)

IMPORTANT: Create the release manually with gh CLI. Do NOT rely on GitHub Actions.

gh release create vX.Y.Z \
  --repo roomi-fields/obsidian-substack \
  --title "vX.Y.Z" \
  --notes "Release notes here..." \
  main.js manifest.json styles.css

The release MUST include these files as assets:

  • main.js - Compiled plugin code
  • manifest.json - Plugin manifest
  • styles.css - Plugin styles

8. Deploy to Test Vault (Optional)

powershell -ExecutionPolicy Bypass -File "deployment/scripts/deploy.ps1"

Troubleshooting

Release already exists

If creating a release fails because it already exists:

# Delete existing release
gh release delete vX.Y.Z --repo roomi-fields/obsidian-substack --yes

# Delete and recreate tag
git tag -d vX.Y.Z
git push origin :refs/tags/vX.Y.Z
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

# Create release again
gh release create vX.Y.Z ...

Tag already exists

git tag -d vX.Y.Z
git push origin :refs/tags/vX.Y.Z

Version mismatch

Always update ALL version files:

  • package.json
  • manifest.json
  • versions.json

Why Manual Releases?

The GitHub Actions release workflow (.github/workflows/release.yml) is disabled because:

  1. We create releases manually with specific release notes
  2. Automated releases would conflict with manually created ones
  3. Manual control allows better release note customization

To re-enable automated releases, edit .github/workflows/release.yml and uncomment the on: push: tags: section.