Implement tag-based release workflow with marketplace publishing

.github/workflows/release.yml

@@ -1,9 +1,9 @@
 name: release extension
 
 on:
-    push:
-      tags:
-        - '*'
+  push:
+    tags:
+      - '*'
 
 jobs:
   build:
@@ -12,22 +12,98 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
+    - name: Extract tag name
+      id: extract_tag
+      run: |
+        TAG=${GITHUB_REF#refs/tags/}
+        echo "tag=$TAG" >> $GITHUB_OUTPUT
+        echo "Extracted tag: $TAG"
+
+    - name: Validate tag format and determine release type
+      id: validate_tag
+      run: |
+        TAG="${{ steps.extract_tag.outputs.tag }}"
+
+        # Check if tag matches stable release pattern (e.g., 1.0.3)
+        if echo "$TAG" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+          echo "is_stable_release=true" >> $GITHUB_OUTPUT
+          echo "is_prerelease=false" >> $GITHUB_OUTPUT
+          echo "should_publish=true" >> $GITHUB_OUTPUT
+          echo "Tag is a stable release: $TAG"
+        # Check if tag matches pre-release pattern (e.g., 1.0.3-alpha, 1.0.3-beta, 1.0.3-rc.1)
+        elif echo "$TAG" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+-.+$'; then
+          echo "is_stable_release=false" >> $GITHUB_OUTPUT
+          echo "is_prerelease=true" >> $GITHUB_OUTPUT
+          echo "should_publish=true" >> $GITHUB_OUTPUT
+          echo "Tag is a pre-release: $TAG"
+        else
+          echo "is_stable_release=false" >> $GITHUB_OUTPUT
+          echo "is_prerelease=false" >> $GITHUB_OUTPUT
+          echo "should_publish=false" >> $GITHUB_OUTPUT
+          echo "Tag does not match release patterns: $TAG"
+          echo "Will only run build and test."
+        fi
+
+    - name: Extract version from tag
+      id: extract_version
+      if: steps.validate_tag.outputs.should_publish == 'true'
+      run: |
+        TAG="${{ steps.extract_tag.outputs.tag }}"
+        # Extract the version number (e.g., 1.0.3 from 1.0.3 or 1.0.3-alpha)
+        VERSION=$(echo "$TAG" | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+')
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        echo "Extracted version: $VERSION"
+
+    - name: Check version consistency with package.json
+      if: steps.validate_tag.outputs.should_publish == 'true'
+      run: |
+        TAG_VERSION="${{ steps.extract_version.outputs.version }}"
+        PACKAGE_VERSION=$(node -p "require('./package.json').version")
+
+        echo "Tag version: $TAG_VERSION"
+        echo "package.json version: $PACKAGE_VERSION"
+
+        if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then
+          echo "Error: Tag version ($TAG_VERSION) does not match package.json version ($PACKAGE_VERSION)"
+          exit 1
+        fi
+
+        echo "Version check passed: $TAG_VERSION"
+
     - name: Use Node.js
       uses: actions/setup-node@v3
       with:
         node-version: 21.x
 
+    - name: Install dependencies
+      run: npm install
+
     - name: Build
-      run: |
-        npm install
-        npx tsc
+      run: npx tsc
+
     - name: Install VSCE
-      run: npm install -g vsce
+      run: npm install -g @vscode/vsce
+
     - name: Build VSIX
       run: vsce package
-    - name: GitHub Release
+
+    - name: Publish to VS Code Marketplace
+      if: steps.validate_tag.outputs.should_publish == 'true'
+      env:
+        VSCE_PAT: ${{ secrets.MS_STORE_TOKEN }}
+      run: |
+        if [ "${{ steps.validate_tag.outputs.is_stable_release }}" == "true" ]; then
+          echo "Publishing as stable release to VS Code Marketplace..."
+          vsce publish -p $VSCE_PAT
+        else
+          echo "Publishing as pre-release to VS Code Marketplace..."
+          vsce publish --pre-release -p $VSCE_PAT
+        fi
+
+    - name: Create GitHub Release
+      if: steps.validate_tag.outputs.should_publish == 'true'
       uses: softprops/action-gh-release@v2
-      if: startsWith(github.ref, 'refs/tags/')
       with:
         files: ./*.vsix
-        prerelease: true
+        prerelease: ${{ steps.validate_tag.outputs.is_prerelease }}
+        generate_release_notes: true

RELEASE_WORKFLOW.md

@@ -0,0 +1,148 @@
+# Release Workflow Documentation
+
+This document describes the automated release workflow for the EGE VSCode Plugin.
+
+## Overview
+
+The release workflow is triggered when you push a git tag to the repository. The behavior depends on the tag format:
+
+### Tag Formats
+
+#### 1. Stable Release Tags
+**Pattern:** `X.Y.Z` (e.g., `1.0.3`, `2.1.0`)
+- **Regex:** `/^[0-9]+\.[0-9]+\.[0-9]+$/`
+- **Behavior:**
+  - Builds and tests the extension
+  - Validates tag version matches `package.json` version
+  - Publishes to VS Code Marketplace as a **stable release**
+  - Creates a GitHub release (not marked as pre-release)
+  - Attaches VSIX file to GitHub release
+
+#### 2. Pre-Release Tags
+**Pattern:** `X.Y.Z-suffix` (e.g., `1.0.3-alpha`, `1.0.3-beta`, `1.0.3-rc.1`)
+- **Regex:** `/^[0-9]+\.[0-9]+\.[0-9]+-.+$/`
+- **Supported suffixes:** `-alpha`, `-beta`, `-rc`, `-rc.1`, etc.
+- **Behavior:**
+  - Builds and tests the extension
+  - Validates tag version (numeric part) matches `package.json` version
+  - Publishes to VS Code Marketplace as a **pre-release**
+  - Creates a GitHub release (marked as pre-release)
+  - Attaches VSIX file to GitHub release
+
+**Important:** The VS Code Marketplace doesn't support version suffixes in the actual extension version. The pre-release suffix is only used in the git tag name. The actual version in `package.json` should be the numeric version only (e.g., `1.0.3`).
+
+#### 3. Non-Release Tags
+**Examples:** `v1.0.3`, `latest`, `dev`, `test`
+- **Behavior:**
+  - Builds and tests the extension
+  - **Does NOT publish** to marketplace
+  - **Does NOT create** GitHub release
+  - Useful for testing the build process
+
+## Version Consistency Check
+
+For all release tags (both stable and pre-release), the workflow validates that:
+- The numeric version in the tag matches the version in `package.json`
+- If they don't match, the workflow fails with an error
+
+**Example:**
+- Tag: `1.0.3` → Must match `package.json` version `1.0.3` ✓
+- Tag: `1.0.3-alpha` → Must match `package.json` version `1.0.3` ✓
+- Tag: `1.0.4` → If `package.json` has `1.0.3`, workflow fails ✗
+
+## How to Create a Release
+
+### Stable Release
+
+1. Update the version in `package.json`:
+   ```bash
+   # Edit package.json and set "version": "1.0.4"
+   ```
+
+2. Commit the version change:
+   ```bash
+   git add package.json
+   git commit -m "Bump version to 1.0.4"
+   git push
+   ```
+
+3. Create and push a tag:
+   ```bash
+   git tag 1.0.4
+   git push origin 1.0.4
+   ```
+
+### Pre-Release
+
+1. Update the version in `package.json` to the base version:
+   ```bash
+   # Edit package.json and set "version": "1.0.4"
+   ```
+
+2. Commit the version change:
+   ```bash
+   git add package.json
+   git commit -m "Bump version to 1.0.4"
+   git push
+   ```
+
+3. Create and push a pre-release tag:
+   ```bash
+   git tag 1.0.4-beta
+   git push origin 1.0.4-beta
+   ```
+
+## Required Secrets
+
+The workflow requires the following GitHub secret:
+- `MS_STORE_TOKEN`: Personal Access Token for publishing to VS Code Marketplace
+
+## Workflow Steps
+
+1. **Extract Tag Name** - Gets the tag that triggered the workflow
+2. **Validate Tag Format** - Determines if it's stable, pre-release, or non-release
+3. **Extract Version** - Extracts numeric version from tag (for release tags only)
+4. **Check Version Consistency** - Validates tag version matches package.json
+5. **Setup Node.js** - Installs Node.js environment
+6. **Install Dependencies** - Runs `npm install`
+7. **Build** - Compiles TypeScript to JavaScript
+8. **Install VSCE** - Installs VS Code Extension packaging tool
+9. **Build VSIX** - Creates the extension package
+10. **Publish to Marketplace** - Publishes to VS Code Marketplace (release tags only)
+11. **Create GitHub Release** - Creates GitHub release with VSIX file (release tags only)
+
+## Troubleshooting
+
+### Workflow fails with "Version mismatch"
+- Ensure the tag version matches the version in `package.json`
+- For pre-release tags, only the numeric part needs to match
+
+### Marketplace publish fails
+- Check that `MS_STORE_TOKEN` secret is correctly configured
+- Verify the token has appropriate permissions
+- The workflow will fail if marketplace publishing fails
+
+### Build or test fails
+- The workflow runs for all tags, even non-release tags
+- Fix build or test issues before creating release tags
+
+## Examples
+
+### Valid Stable Release Tags
+- `1.0.3`
+- `2.0.0`
+- `10.20.30`
+
+### Valid Pre-Release Tags
+- `1.0.3-alpha`
+- `1.0.3-beta`
+- `1.0.3-rc`
+- `1.0.3-rc.1`
+- `2.0.0-beta.2`
+
+### Non-Release Tags (Build & Test Only)
+- `v1.0.3` (has 'v' prefix)
+- `latest`
+- `dev`
+- `test`
+- `1.0` (incomplete version)