| 1 | # Publishing to the VS Code Marketplace and Open VSX |
| 2 | |
| 3 | The extension is served by every Diffinery instance (`/-/vscode/diffinery.vsix`, built by |
| 4 | `apps/diffinery/scripts/build-docs.mjs`). These are the steps for listing it on the marketplaces as well. Cursor, |
| 5 | Windsurf and VSCodium install from Open VSX; VS Code installs from the Visual Studio Marketplace, so both are needed. |
| 6 | |
| 7 | ## Before the first upload |
| 8 | |
| 9 | 1. Create the `codician` publisher on the Marketplace (https://marketplace.visualstudio.com/manage, display name |
| 10 | **Codician**; a personal access token for command-line uploads needs an Azure DevOps organization) and the |
| 11 | `codician` namespace on Open VSX (`pnpm dlx ovsx create-namespace codician`, after signing the Eclipse publisher |
| 12 | agreement). The extension id `codician.diffinery` is what the server's OAuth client (`EDITOR_EXTENSION_ID` in |
| 13 | `apps/diffinery/src/auth/oauth.ts`) and the docs use, so keep it. |
| 14 | 2. The package already carries the license (`"license": "Apache-2.0"` and the repository's `LICENSE` as |
| 15 | `extension/LICENSE.txt`), and the marketplace build (`--marketplace` below) ships with `diffinery.checkForUpdates` |
| 16 | off by default, so the marketplace's updates and the extension's own check against the Diffinery server don't |
| 17 | fight. |
| 18 | |
| 19 | ## Listing |
| 20 | |
| 21 | | Field | Value | |
| 22 | | --- | --- | |
| 23 | | Name | Diffinery | |
| 24 | | Short description | `description` in `package.json` | |
| 25 | | Categories | SCM Providers, Other | |
| 26 | | Icon | `media/icon.png` (128×128) | |
| 27 | | Banner | `galleryBanner` in `package.json` | |
| 28 | | Details page | `README.md` (relative image links are rewritten to the repository) | |
| 29 | | Changelog | `CHANGELOG.md` | |
| 30 | | Q&A / issues | `bugs.url` in `package.json` | |
| 31 | |
| 32 | ## Each release |
| 33 | |
| 34 | 1. Bump `version` in `package.json` and add a `CHANGELOG.md` entry. |
| 35 | 2. `node scripts/package.mjs --out dist --marketplace` builds `dist/diffinery-<version>-marketplace.vsix` |
| 36 | (without `--marketplace`, `dist/diffinery-<version>.vsix` is the file diffinery.com serves). |
| 37 | 3. Upload it on the publisher's page (**New extension → Visual Studio Code**, or **Update** on the extension) and on |
| 38 | Open VSX, or from the command line: `pnpm dlx @vscode/vsce publish --packagePath dist/diffinery-<version>-marketplace.vsix` and |
| 39 | `pnpm dlx ovsx publish dist/diffinery-<version>-marketplace.vsix`, with the tokens from step 1 of *Before the first upload* in `VSCE_PAT` and `OVSX_PAT`. |
| 40 | 4. Deploying Diffinery keeps diffinery.com serving the same version for people who installed from there. |