Skip to content

PUBLISHING.md

Latest commit

 

History

History
149 lines (111 loc) · 6.46 KB

PUBLISHING.md

File metadata and controls

149 lines (111 loc) · 6.46 KB
Raw

Publishing Herdex

How to publish the Herdex extension to the VS Code Marketplace (and, optionally, Open VSX). Everything the CI/build already handles is noted; the rest are one-time or per-release steps.

Current state: publisher in package.json is the placeholder herd and the icon field is unset. Both must be resolved before a real publish (see Pre-flight).

One-time setup

1. Create a Marketplace publisher

The Marketplace is backed by Azure DevOps.

  1. Sign in at https://marketplace.visualstudio.com/manage with a Microsoft account.
  2. Create publisher → pick a publisher ID (lowercase, unique, e.g. mkellerman) and a display name. The ID is permanent and becomes part of the extension id ‹publisher›.vscode-herdr.
  3. Set it in package.json: 
    "publisher": "mkellerman"
    Keep the repository, bugs, and homepage URLs in sync with the real repo.

2. Create a Personal Access Token (PAT)

  1. Go to https://dev.azure.com (same Microsoft account) → User settings → Personal access tokens → New Token.
  2. Organization: All accessible organizations. Expiration: your call.
  3. Scopes: Custom defined → Marketplace → Manage (only that).
  4. Copy the token — it's shown once. Store it in a password manager.

3. Make it available to whichever path you publish from

  • Locally: you'll pass it per publish (or vsce login <publisher> once).
  • CI (recommended): add it as a GitHub Actions secret named VSCE_PAT (repo → Settings → Secrets and variables → Actions → New repository secret). The publish job in .github/workflows/ci.yml already reads it.

Pre-flight checklist

Do these before the first publish:

  • publisher set to your real publisher ID (not herd).
  • Icon — add a 128×128+ PNG (SVG is not allowed for the gallery icon), e.g. media/icon.png, and set "icon": "media/icon.png" in package.json. ⚠️ Decide branding first: shipping Herdr's logo/name may be a trademark issue — the README already frames Herdex as an unofficial/community client.
  • Screenshots/GIF in the README (replace the <!-- TODO --> placeholders). This is the single biggest factor in whether people install.
  • README.md reads well as the Marketplace page (it's rendered verbatim) and states "requires Herdr installed and running."
  • CHANGELOG.md has an entry for the version you're shipping.
  • Version in package.json is correct (SemVer) and not already published.
  • Green build: pnpm run typecheck && pnpm run lint && pnpm run test.
  • Sanity-check the package contents: npx @vscode/vsce ls (should be dist/extension.js, package.json, README, LICENSE, CHANGELOG, media/** — no src, test, node_modules, or lockfiles).

Publishing

Option A — CI on a version tag (recommended, tag-driven)

The git tag is the single source of truth for the version. With VSCE_PAT set as a repo secret, publishing is just tagging:

git tag v0.1.1        # the version to publish (SemVer, with a leading v)
git push origin v0.1.1

Pushing a v* tag triggers the publish job in .github/workflows/ci.yml, which derives the version from the tag (v0.1.1 → 0.1.1), sets it in package.json for the build (npm version … --no-git-tag-version), packages herdex-<version>.vsix, and runs vsce publish.

Because the version comes from the tag, the version in a committed package.json is just a dev placeholder — you don't need to bump it to release. Do keep CHANGELOG.md updated with an entry for the version you're tagging. For a pre-release, tag e.g. v0.2.0-beta.1 (and add --pre-release to the vsce step if you want it flagged pre-release on the Marketplace).

Option B — publish locally

pnpm run package                                   # -> herdex-<version>.vsix (build + vsce package)

# authenticate once, then publish the built vsix:
npx @vscode/vsce login <publisher>                 # paste the PAT when prompted
npx @vscode/vsce publish --packagePath herdex-<version>.vsix

# …or publish + bump the version in one step (creates a git commit + tag):
npx @vscode/vsce publish patch -p "$VSCE_PAT"      # minor | major | <version>

After publishing, the listing appears at https://marketplace.visualstudio.com/items?itemName=<publisher>.vscode-herdr (indexing can take a few minutes).

Optional — Open VSX (VSCodium, Cursor, Gitpod, …)

Many editors that aren't official VS Code use the Open VSX registry. Since Herdex targets AI-agent users (some on Cursor/VSCodium), consider publishing there too:

  1. Create an account at https://open-vsx.org and an access token.
  2. npx ovsx publish herdex-<version>.vsix -p <OPEN_VSX_TOKEN>

(You may need to create the namespace once: npx ovsx create-namespace <publisher> -p <token>.)

Versioning & releases

  • SemVer. Patch = fixes, minor = features, major = breaking. Pre-1.0, breaking changes can ride minor bumps, but keep the CHANGELOG honest.
  • The git tag is the source of truth (tag-driven). To release, tag vX.Y.Z and push it — CI stamps that version into the build and publishes. Update CHANGELOG.md before tagging. (Publishing locally with vsce publish <version> still works if you prefer, but the tag path avoids version drift.)
  • Protocol coupling: Herdex targets Herdr wire protocol EXPECTED_PROTOCOL (see src/runtime/types.ts, currently 17). If Herdr bumps its protocol, re-run herdr api schema --json, reconcile docs/research/herdr-socket-api.md, update the constant, and ship a release.

Troubleshooting

  • ERROR Missing publisher name — set publisher in package.json.
  • 401 Unauthorized — PAT wrong/expired, or not Marketplace → Manage scope, or not scoped to all accessible organizations.
  • ERROR ... icon ... must be a PNG — the icon field must point to a PNG.
  • Relative-link warning about docs/... — vsce resolves README links against repository; it's set, so this should be quiet. If it complains, the link target isn't in the repo or the URL is wrong.
  • Version already exists — you can't republish the same version; bump it.
  • vsce/ovsx not found — the scripts use npx @vscode/vsce; @vscode/vsce is also a devDependency, so pnpm install provides it locally.