Open in vscode.dev Install

Releasing

The release checklist: version, changelog, tests, recordings, the documentation check, the .vsix, the Marketplace, the tag and the site.

A release is a version on the Visual Studio Marketplace, a v<version> tag with the .vsix attached to a GitHub release, and the documentation site of that version. Go through the list in order; each step names the command and what to look at. The example is 1.2.0.

1. Version and changelog#

  1. Set the version in package.json and package-lock.json: npm version 1.2.0 --no-git-tag-version changes both.
  2. Run npm run docs:gen: scripts/docs-data.mjs writes the version into docs.src/data/site.json, which the product page’s hero and the footer show.
  3. In CHANGELOG.md, turn the version’s section into release notes: ## 1.2.0 (2026-10-18) — <title>, a short Highlights paragraph, then the entries. Keep the next version’s section as ## 1.3.0 (unreleased) — …. The release workflow refuses a tag whose version has no ## <version> heading.
  4. Read README.md as the Marketplace listing: the features, the plans and the install lines must match this version. Its images are absolute https:// URLs on the documentation site, which the Marketplace requires; the links point at the site or the repository.

2. Build and test#

sh
npm ci
npm run compile
npm run lint                 # ESLint, layer rules, l10n, and the documentation check (docs:check)
npm run test                 # unit tests and the webview contract
xvfb-run -a npm run test:integration    # on Linux; without xvfb-run elsewhere
npm run test:web             # the extension in VS Code for the Web (Chromium)
node scripts/check-licences.mjs --check

All of them must pass. npm run lint runs npm run docs:check, so a guide page without a clip, a command missing from the guide or the reference, or a broken link in the built site fails it (see Keeping the documentation current).

3. Recordings, when the UI changed#

The clips and casts are committed. When a release changes what they show (a panel, a menu, a command’s output), record them again and look at them before committing:

sh
npm run docs:record -- --all --sheet /tmp/sheets   # the editor clips; the contact sheets to check them
npm run docs:cast -- --all                         # the terminal casts
npm run docs:check                                 # every page has its recording, nothing is orphaned

Recording one clip or cast is npm run docs:record -- <name> / npm run docs:cast -- <name>. What each needs (Chromium, ffmpeg, asciinema, agg) is in scripts/docs/README.md. The scheduled workflow docs-check.yml records everything again every week and on a release tag, and compares the lengths and frame counts with the committed ones.

4. The documentation site#

sh
npm run docs:gen      # specifications, the ud reference, plans and version
npm run docs:build    # hugo into docs/
npm run docs:check    # the guide, the recordings, the reference and the links of the built site
npm run docs:serve    # look at it: the product page, the guide, the version in the footer

5. Package and try the .vsix#

sh
npm run package       # softforge-ui-designer-1.2.0.vsix, then the 25 MB budget check
npx @vscode/vsce ls   # the files that go into the package

The list must hold dist/, media/ (with media/dist, media/fonts, media/wasm), l10n/, package.nls*.json, skills/, schemas/, the icon, LICENSE, THIRD-PARTY-NOTICES, README.md and CHANGELOG.md, and nothing of src/, test/, docs.src/, docs/, site/, scripts/, sample/ or node_modules/ (.vscodeignore keeps them out).

Then install it on a clean profile and try it:

  1. code --profile release-check --install-extension softforge-ui-designer-1.2.0.vsix, open a folder, run UI Designer: New Design, draw, save, undo, open the Subscription menu.
  2. In a new integrated terminal: ud version, ud tree <file>, ud help mcp.
  3. npm run test:web covers VS Code for the Web; open a repository on vscode.dev with the .vsix installed (Extensions: Install from VSIX…) for a last look.

6. Publish#

  1. npx @vscode/vsce publish --packagePath softforge-ui-designer-1.2.0.vsix with the publisher’s Personal Access Token (VSCE_PAT, scope Marketplace ▸ Manage, organisation All accessible organizations). Publishing the file you tested publishes exactly what you tried.
  2. Tag the commit and push the tag: git tag v1.2.0 && git push origin v1.2.0. .github/workflows/release.yml checks that the tag matches package.json and the changelog, runs lint and the unit tests, packages the .vsix and attaches it to a GitHub release.
  3. The documentation site deploys on push: .github/workflows/docs.yml runs docs:gen, docs:build and docs:check -- --no-record and publishes docs/ to GitHub Pages. Check the product page shows the new version.
  4. Check the Marketplace page: the icon, the banner, the README images and the changelog tab.
  5. Announce: the release notes (the changelog’s Highlights) where the users are.

For the owner#

Plans are sold only by a build connected to its product on the Soft Forge Payments platform:

  • Once, from your own machine: npm run platform:connect -- https://host/payments. It signs you in as an owner of the business in the browser, creates the product and the plans of plans.json, and writes src/licensing/productConfig.ts and the sponsor link of package.json. The platform app key goes into .platform/, which is never committed or packaged.
  • After changing plans.json: npm run platform:sync, then npm run docs:gen so the product page shows the same plans (docs:check compares them).
  • Before publishing, check that src/licensing/productConfig.ts points at the production platform.

Edit this page