Skip to content

release-workflow.md

Latest commit

 

History

History
118 lines (75 loc) · 4.19 KB

release-workflow.md

File metadata and controls

118 lines (75 loc) · 4.19 KB
Raw

Release Workflow

This document covers the steps to publish a new version of Ralphdex to the VS Code Marketplace.

Prerequisites

Steps

1. Validate the baseline

npm run validate

Run this from the Ralphdex repo root. All checks (compile, docs, ledger, prompt-budget, lint, tests) must pass before proceeding.

2. Bump the version

Edit package.json and increment version following semver:

Change type Example bump
Bug fix / patch 0.1.0 → 0.1.1
New feature, backwards-compatible 0.1.0 → 0.2.0
Breaking change 0.1.0 → 1.0.0

3. Update CHANGELOG.md

Add a new ## [x.y.z] — YYYY-MM-DD section at the top of CHANGELOG.md describing the operator-visible changes in the release. Keep the newest entry first.

4. Smoke-test the package locally

npm run package

This runs check:runtime then vsce package. Inspect the generated .vsix for 0 blocking warnings before continuing.

5. Run the repo-level dry-run script

npm run publish:dry-run

Run this from the Ralphdex repo root after npm run package succeeds. In the current script surface, publish:dry-run aliases npm run package, so it validates CHANGELOG format, file inclusion, runtime dependency inclusion, and packaging integrity without publishing a Marketplace release.

Treat this as a packaging-readiness check before the real publish command.

6. Commit and tag

git add package.json CHANGELOG.md README.md docs/release-workflow.md
git commit -m "chore(release): bump version to x.y.z"
git tag v<x.y.z>
git push origin main --tags

If the release only changes version and changelog content, stage just those files. Include README.md or release docs when the Marketplace-facing install or publish guidance changed.

7. Publish

npx vsce publish

Run this from the Ralphdex repo root only after npm run publish:dry-run succeeds. vsce will prompt for the PAT if VSCE_PAT is not set in the environment. Alternatively:

VSCE_PAT=<token> npx vsce publish

8. Verify on the Marketplace

Visit the Marketplace listing and publisher page to confirm the new version is live and the README-rendered metadata look correct:

https://marketplace.visualstudio.com/items?itemName=s0l0m0n8und9.ralphdex

https://marketplace.visualstudio.com/manage/publishers/s0l0m0n8und9

Confirm at minimum:

  • the version matches package.json
  • the README renders the install and post-install tour sections correctly
  • the icon, banner, and repo/support links resolve to the current Ralphdex project

Skipped or undocumented versions

If a version number was bumped in package.json but never had a CHANGELOG entry written (for example, intermediate preparatory bumps that were superseded before publishing), backfill the entry from the corresponding commits rather than leaving a gap. To identify what belongs in the entry, run:

git log --oneline <previous-version-bump-sha>..<this-version-bump-sha>

Add the backfilled entry in the correct chronological position in CHANGELOG.md with the date from the version-bump commit (git show --format="%ci" --no-patch <sha>). If the version was intentionally abandoned with no meaningful changes, add a one-line note in its place:

## [x.y.z] — YYYY-MM-DD

> Preparatory version bump — superseded before publishing; no operator-visible changes.

Do not leave silent gaps — future maintainers and downstream tooling rely on a contiguous version history.

Rollback

If a bad version ships, yank it from the Marketplace management page and publish a patch release.
Do not delete the git tag — use it as a reference for the revert diff.

Environment variable reference

Variable Purpose
VSCE_PAT Marketplace PAT for vsce publish — keep out of source control