zotoio/xfi-release-workflow

X-Fidelity Release Workflow

This skill guides you through the unified release process for X-Fidelity.

Release System Overview

X-Fidelity uses a unified release system that synchronizes versions between:

• CLI package (x-fidelity) - Published to npm
• VSCode extension (x-fidelity-vscode) - Published to VS Marketplace and Open VSX

Both packages always share the same version number.

Commit Convention Reference

Releases are triggered automatically by conventional commits. Use yarn commit for guided commit creation.

Release-Triggering Commits

| Type | Version Bump | Example | |------|--------------|---------| | feat: | Minor (0.X.0) | feat: add new rule for React hooks | | fix: | Patch (0.0.X) | fix: resolve AST parsing for arrow functions | | perf: | Patch | perf: optimize file scanning | | revert: | Patch | revert: undo breaking change | | bump: | Patch | bump: update dependencies | | BREAKING CHANGE: | Major (X.0.0) | Include in commit body |

Non-Release Commits

These do NOT trigger releases:

| Type | Use For | |------|---------| | docs: | Documentation changes | | style: | Code formatting, whitespace | | chore: | Maintenance, tooling | | refactor: | Code restructuring without behavior change | | test: | Adding or updating tests | | build: | Build system changes | | ci: | CI/CD changes |

Commit Format

type(scope): subject

body (optional)

footer (optional)

Examples:

# Feature (minor release)
feat(plugins): add new complexity threshold operator

# Bug fix (patch release)  
fix(vscode): resolve diagnostic not clearing on fix

# Breaking change (major release)
feat(core): redesign plugin initialization API

BREAKING CHANGE: Plugin initialize() now receives PluginContext instead of logger

Workflow Checklist

Release Workflow:
- [ ] Ensure all tests pass: yarn test
- [ ] Verify build succeeds: yarn build
- [ ] Create conventional commit
- [ ] Push to master branch
- [ ] Monitor GitHub Actions
- [ ] Verify published packages

Local Testing

Dry Run

Test what would be released without actually publishing:

yarn release:dry-run

This shows:

• Next version number
• Changelog preview
• Packages that would be published

Full Local Release (Development)

# Requires environment variables
GH_TOKEN=xxx VSCE_PAT=xxx OVSX_PAT=xxx yarn release

Automated Release Process

When commits are pushed to master:

1. Commit Analysis: Determines version bump from commit messages
2. Version Update: Updates package.json in CLI and VSCode packages
3. Changelog Generation: Updates CHANGELOG.md
4. Build: Runs production builds
5. Publish CLI: Publishes to npm via OIDC trusted publishing
6. Publish VSCode: Publishes to VS Marketplace and Open VSX
7. GitHub Release: Creates release with VSIX and CLI artifacts
8. Git Commit: Commits version bumps back to repo

Environment Variables

For local releases or CI configuration:

| Variable | Purpose | Where to Get | |----------|---------|--------------| | GH_TOKEN | GitHub releases and git operations | GitHub Settings > Developer settings > PAT | | VSCE_PAT | VS Code Marketplace publishing | VS Marketplace > Manage Publishers | | OVSX_PAT | Open VSX Registry publishing | Open VSX > Access Tokens |

Note: NPM_TOKEN is not required - CLI uses npm trusted publishing via OIDC.

Troubleshooting

Release Not Triggered

1. Check commit format: Must follow conventional commits
2. Verify commit type: Only feat, fix, perf, revert, bump trigger releases
3. Check branch: Must be on master (or beta for prereleases)

# View recent commits with their types
git log --oneline -10

Partial Release Failure

If one package fails to publish:

1. Check GitHub Actions workflow logs
2. CLI and VSCode publishing are independent
3. Retry by pushing an empty fix commit:

git commit --allow-empty -m "fix: retry release"
git push

Version Mismatch

Should not occur with unified releases. If it does:

1. Check both package.json files have same version
2. Verify last release commit wasn't corrupted
3. Run yarn release:dry-run to see expected state

Token Errors

# Test VS Marketplace token
vsce verify-pat -p $VSCE_PAT

# Test GitHub token
gh auth status

Release Branches

| Branch | Release Type | npm Tag | |--------|--------------|---------| | master | Stable | latest | | beta | Prerelease | beta |

Prerelease versions: 1.2.3-beta.1, 1.2.3-beta.2, etc.

Post-Release Verification

After release completes:

# Verify npm package
npm view x-fidelity version

# Verify global install
npm install -g x-fidelity@latest
xfi --version

# Check VS Marketplace
# Visit: https://marketplace.visualstudio.com/items?itemName=zotoio.x-fidelity-vscode

Key Files

| File | Purpose | |------|---------| | .releaserc.json | semantic-release configuration | | scripts/prepare-unified-release.js | Pre-publish version updates | | scripts/publish-unified-release.js | Publish both packages | | .github/workflows/release-unified.yml | GitHub Actions workflow | | CHANGELOG.md | Auto-generated changelog |

Quick Reference

# Create proper commit
yarn commit

# Test release locally
yarn release:dry-run

# View changelog
cat CHANGELOG.md

# Check current versions
cat packages/x-fidelity-cli/package.json | grep version
cat packages/x-fidelity-vscode/package.json | grep version