releasing

How a change gets from the working tree to the stores, and the traps that cost a round trip the last time each one was hit. ## The path `main` is the branch that ships. `poc` carries the retired proof of concept and nothing merges there. Work lands on a feature branch, goes into `main` through a PR, and the merge is what publishes. 1. Commit on the feature branch (only when the [user] says so). If the change touches `extension-vscode/`, `extension-browser/` or `packages/weft-graph/` (both editors bundle it), bump that package's version IN THE SAME PR (`pnpm version patch --no-git-tag-version` in the package directory): a merge without a bump publishes nothing to the stores. The `extension versions bumped` CI check refuses a PR that forgot; `scripts/check-extension-bump.sh origin/main` is the same check locally. 2. `gh pr create --base main --head <branch>`. 3. `gh pr merge <n> --auto --merge`, which lands it the moment CI passes. Earlier PRs into `main` are merge commits, so match that. 4. The push to `main` runs `release.yml`, which builds the images, the CLI binaries, the `.vsix` and the browser zips, updates the rolling `latest` release, and then publishes to each store. CI runs on `pull_request` into `main` only. Six checks: `extension versions bumped` (PRs only), `build`, `public proxy routes`, `cargo test + clippy`, `cargo test --features db-tests`, and `graph + editor`. ## Run the checks CI runs, not the ones you touched `cargo clippy --workspace --all-targets --locked -- -D warnings` is the CI line. Running clippy on the crates you edited is not the same thing and has already sent a PR red on a lint in a crate the change only touched indirectly. `scripts/validate-examples.sh` compiles every example. It fails on ERRORS only, so a warning is advice an example may carry. If an example starts failing after a language change, the question is whether the example is wrong or the diagnostic is, and the answer has been "the diagnostic" as often as not. ## The record tags decide what publishes Each successful publish is recorded as a git tag, `<prefix>-<store>-v<version>`: `vscode-marketplace-v0.2.239`, `browser-firefox-v1.0.62`. Before publishing, the workflow asks `git ls-remote origin refs/tags/<tag>` per store; a store whose tag exists gets no job at all. So **a store publishes exactly when its tag is missing**, and the version in the workspace's `package.json` is what the tag names. Without a version bump, a release republishes nothing. Two things follow, and both have bitten: **Bumping is the release gesture.** `extension-vscode/package.json` and `extension-browser/package.json` carry their own versions. `./setup.sh --bump` (with `--vscode` and/or `--browser`) moves them; so does `pnpm version patch --no-git-tag-version` in the workspace. Push a bump and that store publishes. **A tag that is missing when the store already has the version is a stuck release.** The tag is written after the publish succeeds, so a successful publish whose tag push failed leaves the repo believing the store still owes one. The next run submits a duplicate, the store refuses, and only a hand-made tag ever clears it. That is why `.github/actions/publish-and-record` treats a refusal saying the version is already there as published and records the tag. Every other failure still fails the job. If you ever widen that pattern, the failure mode you are risking is a tag written for a publish that never happened, which skips that store forever. To check the state before a release, or to work out why a job ran: ```bash git ls-remote --tags origin | grep -E "vscode|browser" ``` And to record something a store already has (a manual upload, a publish whose tag was lost), tag the commit whose content is live: ```bash git tag vscode-marketplace-v0.2.239 <commit> && git push origin vscode-marketplace-v0.2.239 ``` ## The stores **VS Code Marketplace.** Publishes with `vsce publish --azure-credential` from the `marketplace-publish` environment. A brand-new publisher gets blocked with "Your extension has suspicious content. Please fix your extension metadata, or contact support if you need assistance", which names nothing and is not documented anywhere. It survived removing an ad-carrying dependency, trimming the package and fixing every link. What cleared it was uploading the `.vsix` by hand at `marketplace.visualstudio.com/manage/publishers/weavemind` ("New extension"). Once the publisher has an accepted extension, CI should work; the next bump is what proves it. If it is blocked again, the question for `vsmarketplace@microsoft.com` is sharp: the package is byte-identical to one they accepted by hand, so the automated path is the only difference. Every documented case of this ends at support. **Open VSX** (`ovsx`) is the store VSCodium, Cursor and Windsurf read. It has never refused anything. Its namespace must exist before the first publish and creating it twice is refused, which the workflow handles. **Chrome, Firefox, Edge** go through `wxt submit` from `extension-browser`. AMO refuses a duplicate version with a 409 naming the version, which is the case the self-heal was written for. Firefox also needs a sources zip (`zip:firefox` writes it) because AMO reviews the source behind a bundle. ## Marketplace package rules worth knowing before packaging Checked against the published rules, and all of these are enforced: - The icon may not be an SVG and must be at least 128x128. - Images in the README must resolve to `https` URLs and may not be SVGs. Relative links are rewritten by `vsce` using the repository field against the `main` branch. Prefer absolute links to the docs site. - Badges are only allowed from approved providers. - `categories` must come from the fixed list; `keywords` caps at 30. - `displayName` must be unique Marketplace-wide. - A licence file must ship. `release.yml` copies the repo `LICENSE` into `extension-vscode/` at package time. `pnpm dlx @vscode/vsce@3.9.2 ls --no-dependencies` lists exactly what would ship, which is how to catch things like compiled tests riding along because `out/` was never cleaned. ## Deployments show red forever The repo's Deployments panel lists the `marketplace-publish` environment with a red mark from a failed run. GitHub keeps the last status per deployment and never revises it, and a job that is SKIPPED creates no deployment at all, so a later green run does not clear it. It is a record of a past attempt, not the current state. The truth is the run's own conclusion and the store itself: ```bash curl -s -X POST 'https://marketplace.visualstudio.com/_apis/public/gallery/extensionquery' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json;api-version=7.2-preview.1' \ -d '{"filters":[{"criteria":[{"filterType":7,"value":"weavemind.weft-vscode"}],"pageSize":5,"pageNumber":1}],"flags":914}' ``` ## A publish job that fails with an empty log `.github/actions/publish-and-record` captures the store's output so it can read the refusal. `shell: bash` runs the step under `-e`, and a `set -uo pipefail` does not lift that, so until the capture was wrapped in `set +e` a failing publish exited on the capture line and the log ended at the `PUBLISH:` echo with nothing from the store. If that shape ever comes back, the store's answer is missing because the script died before printing it, not because the store said nothing. ## What ships even when a store fails Each store publish is its own job, so one refusal never blocks another, and the rolling `latest` release goes out as long as the `.vsix` packaged and the images stitched. That release is what a fresh `./setup.sh` pulls prebuilts from, so a failed store publish costs the listing on that store and nothing else. Say so plainly rather than reporting a release as broken. ## Never run these yourself `./setup.sh` (any flag) and the e2e redeploy the daemon and rebuild the extension while the [user] works, and they take a long time. Ask them to run those. Packaging the `.vsix` (`pnpm run vscode:prepublish && pnpm dlx @vscode/vsce@3.9.2 package --no-dependencies`) is yours: it touches nothing outside `extension-vscode/`.