Merge branch 'main' into feat/i1-stashes-view

Author: zaknafeyn

.github/workflows/pre-release.yml

@@ -0,0 +1,68 @@
+name: Pre-release
+
+on:
+  workflow_dispatch:
+    inputs:
+      force:
+        description: 'Publish even if there are no commits since the last tag'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  pre-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Check for new commits since the last tag
+        id: guard
+        run: |
+          last_tag=$(git describe --tags --abbrev=0 --match 'v*' 2>/dev/null || echo "")
+          if [ "${{ inputs.force }}" = "true" ] || [ -z "$last_tag" ]; then
+            echo "should-release=true" >> "$GITHUB_OUTPUT"
+          elif [ -z "$(git log "$last_tag"..HEAD --oneline)" ]; then
+            echo "should-release=false" >> "$GITHUB_OUTPUT"
+            echo "No commits since $last_tag -- skipping pre-release. Re-run with force=true to override."
+          else
+            echo "should-release=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Setup Node.js
+        if: steps.guard.outputs.should-release == 'true'
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: 'yarn'
+
+      - name: Install dependencies
+        if: steps.guard.outputs.should-release == 'true'
+        run: yarn install --frozen-lockfile
+
+      - name: Generate GitHub App token
+        if: steps.guard.outputs.should-release == 'true'
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
+      - name: Pre-release
+        if: steps.guard.outputs.should-release == 'true'
+        run: yarn semantic-release
+        env:
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+          VSCODE_PAT: ${{ secrets.VSCODE_PAT }}
+          OPEN_VSX_PAT: ${{ secrets.OPEN_VSX_PAT }}
+          POSTHOG_API_KEY: ${{ secrets.POSTHOG_API_KEY }}
+          POSTHOG_HOST: ${{ secrets.POSTHOG_HOST }}
+          RELEASE_CHANNEL: pre

.github/workflows/release.yml

@@ -42,3 +42,4 @@ jobs:
           OPEN_VSX_PAT: ${{ secrets.OPEN_VSX_PAT }}
           POSTHOG_API_KEY: ${{ secrets.POSTHOG_API_KEY }}
           POSTHOG_HOST: ${{ secrets.POSTHOG_HOST }}
+          RELEASE_CHANNEL: stable

CLAUDE.md

@@ -45,6 +45,8 @@ HMR: run `yarn dev`, then launch extension (F5). The extension detects `context.
 - `yarn build-vsix-dev` - Dev VSIX without bundled dependencies
 - `yarn publish` - Publish to VS Code marketplace
 
+Actual Marketplace/Open VSX releases run through `semantic-release` via the `Release` and `Pre-release` GitHub Actions workflows, not these local scripts — see @docs/releasing.md for the stable/pre-release channel strategy.
+
 ## Architecture
 
 See @.claude/rules/architecture.md for full architecture details.

docs/releasing.md

@@ -0,0 +1,71 @@
+# Releasing
+
+Git Smart Checkout publishes to the VS Code Marketplace and Open VSX through two
+GitHub Actions workflows, both driven by `semantic-release` (`release.config.js`)
+and both manual (`workflow_dispatch`) — nothing publishes automatically on push.
+
+## Two channels, one branch
+
+There is no separate `next`/`beta` branch. Both channels release from `main`;
+"pre-release" means *merged to `main` but not yet blessed as stable*, not a
+separate line of code.
+
+| | Stable | Pre-release |
+|---|---|---|
+| Workflow | **Release** (`.github/workflows/release.yml`) | **Pre-release** (`.github/workflows/pre-release.yml`) |
+| Version | `major.EVEN.patch` | `major.ODD.patch` |
+| Packaging | `vsce package` | `vsce package --pre-release` |
+| GitHub release | Latest | marked **Pre-release**, not Latest |
+
+Both lanes share one strictly increasing version sequence and one `v${version}`
+git tag line, so a stable release can never collide with or undercut an
+already-published pre-release.
+
+## Odd/even minor convention
+
+Following [Microsoft's documented convention](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#prerelease-extensions):
+stable releases use an **even** minor, pre-releases use an **odd** minor. The
+bump is mechanical:
+
+- **Pre-release run:** last release had an even minor (or none exists yet) →
+  bump minor; last minor was already odd → bump patch.
+- **Stable run:** last release had an odd minor → force a minor bump (jump
+  over the pre-release corridor); otherwise defer to conventional commits as
+  usual.
+
+```
+stable   0.16.1
+pre      0.17.0   first pre-release of the cycle (minor bump)
+pre      0.17.1   further pre-releases stay on the odd minor (patch bumps)
+pre      0.17.2
+stable   0.18.0   cut stable (minor bump, jumps over 0.17.x)
+pre      0.19.0   next pre-release cycle opens
+```
+
+The bump logic lives in `scripts/nextReleaseType.mjs`, wired into
+`release.config.js` as the `analyzeCommitsCmd` for `@semantic-release/exec`.
+
+**Operational rule:** ship stable patches before opening the next pre-release
+cycle. Once a pre-release minor (e.g. `0.19.0`) is published, the next stable
+release — hotfix or not — jumps to `0.20.0` and carries everything merged to
+`main` since the last stable. This is the cost of the single-branch model.
+
+## Running a release
+
+- **Release** — dispatch from the Actions tab on `main`. Runs `semantic-release`
+  with `RELEASE_CHANNEL=stable`.
+- **Pre-release** — dispatch from the Actions tab on `main`. Runs
+  `semantic-release` with `RELEASE_CHANNEL=pre`. Skips publishing (with a log
+  message) if there are no commits since the last tag, unless the `force`
+  input is set.
+
+Neither workflow requires manual version bumping — `semantic-release` computes
+the next version, updates `package.json`/`CHANGELOG.md`, tags, packages the
+VSIX, and publishes to both registries in one run.
+
+## Opting in to pre-releases
+
+End users switch channels from the VS Code Extensions view: open the Git Smart
+Checkout entry and choose **Switch to Pre-Release Version**. VS Code always
+installs the highest version available on the user's channel, so a pre-release
+user is still offered later stable releases.

release.config.js

@@ -1,8 +1,20 @@
+// Two channels share one version line: stable = major.EVEN.patch, pre-release =
+// major.ODD.patch (see docs/releasing.md). RELEASE_CHANNEL is set by the two
+// dispatchable workflows (release.yml -> 'stable', pre-release.yml -> 'pre') and
+// defaults to 'stable' for local/dry-run use.
+const channel = process.env.RELEASE_CHANNEL === 'pre' ? 'pre' : 'stable';
+const isPre = channel === 'pre';
+
 /** @type {import('semantic-release').GlobalConfig} */
 module.exports = {
   branches: ['main'],
   plugins: [
-    '@semantic-release/commit-analyzer',
+    // Only the stable lane defers to conventional commits. The pre-release lane
+    // must be the sole analyzeCommits authority so it can cap the bump at patch
+    // while on an odd minor -- semantic-release takes the highest type across all
+    // analyzeCommits plugins, so commit-analyzer running here would silently
+    // override that cap.
+    ...(isPre ? [] : ['@semantic-release/commit-analyzer']),
     '@semantic-release/release-notes-generator',
     ['@semantic-release/changelog', {
       changelogFile: 'CHANGELOG.md',
@@ -11,16 +23,27 @@ module.exports = {
       npmPublish: false,
     }],
     ['@semantic-release/exec', {
+      analyzeCommitsCmd: `node scripts/nextReleaseType.mjs ${channel} "\${lastRelease.version}"`,
       // package.json version is already updated by @semantic-release/npm above,
       // so vsce package will embed the correct version in the VSIX filename.
-      prepareCmd: 'yarn build-all && yarn vsce package --yarn',
+      prepareCmd: `yarn build-all && yarn vsce package --yarn${isPre ? ' --pre-release' : ''}`,
       publishCmd:
-        'yarn vsce publish --pat ${process.env.VSCODE_PAT} --packagePath git-smart-checkout-${nextRelease.version}.vsix' +
+        `yarn vsce publish --pat \${process.env.VSCODE_PAT} --packagePath git-smart-checkout-\${nextRelease.version}.vsix${isPre ? ' --pre-release' : ''}` +
+        // ovsx ignores/warns on --pre-release for a prepackaged vsix -- the
+        // Microsoft.VisualStudio.Code.PreRelease marker baked in by `vsce package
+        // --pre-release` above is what Open VSX actually reads.
         ' && yarn ovsx publish --pat ${process.env.OPEN_VSX_PAT} --packagePath git-smart-checkout-${nextRelease.version}.vsix',
+      // semantic-release/github has no `prerelease` option and only infers it from
+      // its own prerelease-branch mode, which this single-branch design doesn't use.
+      ...(isPre && {
+        successCmd: 'gh release edit v${nextRelease.version} --prerelease --latest=false',
+      }),
     }],
     ['@semantic-release/git', {
       assets: ['CHANGELOG.md', 'package.json'],
-      message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
+      message: isPre
+        ? 'chore(pre-release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}'
+        : 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
     }],
     ['@semantic-release/github', {
       assets: [{ path: '*.vsix', label: 'VS Code Extension' }],

scripts/nextReleaseType.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Deterministic release-type resolver for the odd/even minor pre-release convention
+// (stable = major.EVEN.patch, pre-release = major.ODD.patch). Used as the
+// analyzeCommitsCmd for @semantic-release/exec in release.config.js.
+
+/**
+ * @param {'pre' | 'stable'} channel
+ * @param {string | undefined} lastVersion e.g. "0.16.1"
+ * @returns {'major' | 'minor' | 'patch' | ''}
+ */
+export function releaseType(channel, lastVersion) {
+  const minor = lastVersion ? Number(lastVersion.split('.')[1]) : undefined;
+  const isOddMinor = minor !== undefined && minor % 2 !== 0;
+
+  if (channel === 'pre') {
+    return isOddMinor ? 'patch' : 'minor';
+  }
+
+  // stable: jump over the pre-release corridor when the last release was odd;
+  // otherwise defer to @semantic-release/commit-analyzer (no opinion).
+  return isOddMinor ? 'minor' : '';
+}
+
+async function main() {
+  const [channel, lastVersion] = process.argv.slice(2);
+  process.stdout.write(releaseType(channel, lastVersion || undefined));
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}

src/test/unit/nextReleaseType.test.ts

@@ -0,0 +1,31 @@
+import * as assert from 'assert';
+import * as path from 'path';
+
+describe('release type', () => {
+  let releaseType: (channel: 'pre' | 'stable', lastVersion?: string) => string;
+
+  before(async () => {
+    const modulePath = path.join(__dirname, '..', '..', '..', 'scripts', 'nextReleaseType.mjs');
+    ({ releaseType } = await import(modulePath));
+  });
+
+  it('bumps the pre-release channel to the next odd minor after a stable release', () => {
+    assert.strictEqual(releaseType('pre', '0.16.1'), 'minor');
+  });
+
+  it('bumps the pre-release channel to a patch while the minor is already odd', () => {
+    assert.strictEqual(releaseType('pre', '0.17.0'), 'patch');
+  });
+
+  it('bumps to a minor when there is no prior release', () => {
+    assert.strictEqual(releaseType('pre', undefined), 'minor');
+  });
+
+  it('forces a stable minor to jump over an odd pre-release corridor', () => {
+    assert.strictEqual(releaseType('stable', '0.17.3'), 'minor');
+  });
+
+  it('defers to commit-analyzer for a stable release following an even minor', () => {
+    assert.strictEqual(releaseType('stable', '0.18.0'), '');
+  });
+});

website/src/components/VersionBadge/VersionBadge.tsx

@@ -7,6 +7,19 @@ const [PUBLISHER, EXT_NAME] = EXTENSION_ID.split('.');
 
 const MARKETPLACE_URL = `https://marketplace.visualstudio.com/items?itemName=${EXTENSION_ID}`;
 
+// This repo publishes on an odd/even minor convention: stable = major.EVEN.patch,
+// pre-release = major.ODD.patch (see docs/releasing.md). The website badge should
+// only ever advertise the latest stable version.
+function isEvenMinor(version: string): boolean {
+  const minor = Number(version.split('.')[1]);
+  return Number.isFinite(minor) && minor % 2 === 0;
+}
+
+interface GalleryVersion {
+  version?: string;
+  properties?: Array<{ key: string; value: string }>;
+}
+
 async function fetchMsVersion(): Promise<string> {
   const response = await fetch('https://marketplace.visualstudio.com/_apis/public/gallery/extensionquery', {
     method: 'POST',
@@ -16,22 +29,42 @@ async function fetchMsVersion(): Promise<string> {
     },
     body: JSON.stringify({
       filters: [{ criteria: [{ filterType: 7, value: EXTENSION_ID }] }],
-      flags: 950,
+      // Same flags as before minus IncludeLatestVersionOnly (0x200 / 512), so the
+      // full version history comes back (each with `properties`) instead of only
+      // the newest publish -- needed to skip past pre-release versions below.
+      flags: 438,
     }),
   });
   if (!response.ok) throw new Error(`MS API ${response.status}`);
   const data = await response.json();
-  const version: string | undefined = data.results[0].extensions[0].versions[0].version;
-  if (!version) throw new Error('MS API: no version');
-  return version;
+  const versions: GalleryVersion[] = data.results[0].extensions[0].versions ?? [];
+  const stable = versions.find((v) => {
+    if (!v.version) return false;
+    const isPreRelease = v.properties?.some(
+      (p) => p.key === 'Microsoft.VisualStudio.Code.PreRelease' && p.value === 'true'
+    );
+    return !isPreRelease && isEvenMinor(v.version);
+  });
+  if (!stable?.version) throw new Error('MS API: no stable version');
+  return stable.version;
 }
 
 async function fetchOvsxVersion(): Promise<string> {
   const response = await fetch(`https://open-vsx.org/api/${PUBLISHER}/${EXT_NAME}`);
   if (!response.ok) throw new Error(`Open VSX API ${response.status}`);
   const data = await response.json();
   if (!data || data.error || !data.version) throw new Error('Open VSX API: no version');
-  return data.version;
+  if (data.preRelease !== true) return data.version;
+
+  // The latest published version is a pre-release: fall back to the newest
+  // stable (even-minor) entry in the version list rather than fetching every
+  // version's metadata just to read its `preRelease` flag.
+  const allVersions: Record<string, string> = data.allVersions ?? {};
+  const stable = Object.keys(allVersions)
+    .filter((v) => v !== 'latest' && isEvenMinor(v))
+    .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }))[0];
+  if (!stable) throw new Error('Open VSX API: no stable version');
+  return stable;
 }
 
 export function VersionBadge() {