From cb73f747b6aa9774cac3b53667e83bb524122f97 Mon Sep 17 00:00:00 2001
From: Angelo Girardi <girardi.ang@gmail.com>
Date: Mon, 29 Dec 2025 13:50:18 -0600
Subject: [PATCH] chore: fix beta release

---
 .github/workflows/ci.yml             |   9 +-
 .github/workflows/publish-beta.yml   | 120 ++++++++--
 docs/developer/BETA_CHANNEL_GUIDE.md | 335 +++++++++++++++++++--------
 3 files changed, 341 insertions(+), 123 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c12d020..a8dbe19 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,7 +2,14 @@ name: CI
 
 on:
   push:
-    branches: [main, develop]
+    branches: 
+      - main
+      - develop
+      - 'experimental/**'
+      - 'experiment/**'
+      - 'exp/**'
+      - 'feature/**'
+      - 'feat/**'
   pull_request:
     branches: [main, develop]
 
diff --git a/.github/workflows/publish-beta.yml b/.github/workflows/publish-beta.yml
index b11dcbd..9ec65cb 100644
--- a/.github/workflows/publish-beta.yml
+++ b/.github/workflows/publish-beta.yml
@@ -9,6 +9,20 @@ name: Publish Beta (Pre-release)
 on:
   workflow_dispatch:
     inputs:
+      branch:
+        description: "Branch to release from"
+        required: true
+        default: "main"
+        type: string
+      prereleaseType:
+        description: "Pre-release type (alpha for experimental, beta for staging, rc for release candidate)"
+        required: true
+        default: "beta"
+        type: choice
+        options:
+          - "alpha"
+          - "beta"
+          - "rc"
       incrementPatch:
         description: "Increment patch version? (No = first pre-release for this minor)"
         required: true
@@ -17,6 +31,14 @@ on:
         options:
           - "yes"
           - "no"
+      skipMarketplace:
+        description: "Skip publishing to marketplace (just build and create GitHub release)"
+        required: false
+        default: "no"
+        type: choice
+        options:
+          - "yes"
+          - "no"
 
 jobs:
   beta-release:
@@ -29,9 +51,18 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
+          ref: ${{ github.event.inputs.branch }}
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Validate branch exists
+        run: |
+          if ! git rev-parse --verify origin/${{ github.event.inputs.branch }} >/dev/null 2>&1; then
+            echo "❌ Branch '${{ github.event.inputs.branch }}' does not exist!"
+            exit 1
+          fi
+          echo "✅ Branch '${{ github.event.inputs.branch }}' exists"
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
@@ -62,26 +93,54 @@ jobs:
         id: version
         run: |
           CURRENT_VERSION=$(node -p "require('./package.json').version")
+          BRANCH="${{ github.event.inputs.branch }}"
+          PRERELEASE_TYPE="${{ github.event.inputs.prereleaseType }}"
           echo "Current version: $CURRENT_VERSION"
-
-          # Extract major, minor, patch
-          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
-
-          # Check if we're already on an even minor (pre-release track)
-          if [ $((MINOR % 2)) -eq 0 ]; then
-            # Already on pre-release track, just increment patch
-            if [ "${{ github.event.inputs.incrementPatch }}" = "yes" ]; then
-              PATCH=$((PATCH + 1))
+          echo "Branch: $BRANCH"
+          echo "Pre-release type: $PRERELEASE_TYPE"
+
+          # Extract base version (strip any existing prerelease tag)
+          BASE_VERSION=$(echo "$CURRENT_VERSION" | sed -E 's/(-[a-z]+\.[0-9]+)?$//')
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$BASE_VERSION"
+
+          # Check if there's an existing prerelease number to increment
+          EXISTING_PRENUM=$(echo "$CURRENT_VERSION" | grep -oP '(?<=-'"$PRERELEASE_TYPE"'\.)\d+' || echo "0")
+
+          # For non-main branches, include a short branch identifier in the version
+          if [ "$BRANCH" != "main" ]; then
+            # Sanitize branch name (keep only alphanumeric, convert to lowercase)
+            BRANCH_ID=$(echo "$BRANCH" | sed 's/[^a-zA-Z0-9]//g' | tr '[:upper:]' '[:lower:]' | cut -c1-10)
+            
+            # Check if incrementing or starting fresh
+            if echo "$CURRENT_VERSION" | grep -q "$PRERELEASE_TYPE"; then
+              if [ "${{ github.event.inputs.incrementPatch }}" = "yes" ]; then
+                NEW_PRENUM=$((EXISTING_PRENUM + 1))
+              else
+                NEW_PRENUM=$EXISTING_PRENUM
+              fi
+            else
+              NEW_PRENUM=1
             fi
-            NEW_VERSION="${MAJOR}.${MINOR}.${PATCH}"
+            
+            NEW_VERSION="${MAJOR}.${MINOR}.${PATCH}-${PRERELEASE_TYPE}.${NEW_PRENUM}+${BRANCH_ID}"
           else
-            # On stable track (odd minor), move to next even minor for pre-release
-            NEXT_MINOR=$((MINOR + 1))
-            NEW_VERSION="${MAJOR}.${NEXT_MINOR}.0"
+            # Main branch: use standard even/odd versioning
+            if [ $((MINOR % 2)) -eq 0 ]; then
+              # Already on pre-release track, just increment patch
+              if [ "${{ github.event.inputs.incrementPatch }}" = "yes" ]; then
+                PATCH=$((PATCH + 1))
+              fi
+              NEW_VERSION="${MAJOR}.${MINOR}.${PATCH}"
+            else
+              # On stable track (odd minor), move to next even minor for pre-release
+              NEXT_MINOR=$((MINOR + 1))
+              NEW_VERSION="${MAJOR}.${NEXT_MINOR}.0"
+            fi
           fi
 
           echo "New pre-release version: $NEW_VERSION"
           echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+          echo "branch_id=${BRANCH_ID:-main}" >> $GITHUB_OUTPUT
 
       - name: Update version in package.json
         run: |
@@ -104,12 +163,13 @@ jobs:
           echo "VSIX file: $VSIX_FILE"
 
       - name: Publish to VS Code Marketplace (Pre-release)
+        if: github.event.inputs.skipMarketplace != 'yes'
         run: npx @vscode/vsce publish --pre-release -p ${{ secrets.VSCE_PAT }}
         env:
           VSCE_PAT: ${{ secrets.VSCE_PAT }}
 
       - name: Publish to Open VSX (Pre-release)
-        if: env.OVSX_PAT != ''
+        if: github.event.inputs.skipMarketplace != 'yes' && env.OVSX_PAT != ''
         run: npx ovsx publish ${{ steps.vsix.outputs.filename }} --pre-release -p ${{ secrets.OVSX_PAT }}
         env:
           OVSX_PAT: ${{ secrets.OVSX_PAT }}
@@ -118,7 +178,7 @@ jobs:
       - name: Commit version change
         run: |
           git add package.json
-          git commit -m "chore(release): pre-release ${{ steps.version.outputs.new_version }}"
+          git commit -m "chore(release): pre-release ${{ steps.version.outputs.new_version }} from ${{ github.event.inputs.branch }}"
 
       - name: Create Git tag
         run: |
@@ -126,7 +186,7 @@ jobs:
 
       - name: Push changes and tags
         run: |
-          git push origin HEAD:${{ github.ref_name }}
+          git push origin HEAD:${{ github.event.inputs.branch }}
           git push origin v${{ steps.version.outputs.new_version }}
 
       - name: Create GitHub Pre-release
@@ -137,13 +197,16 @@ jobs:
           body: |
             ## 🧪 Pre-release Version
 
-            This is a **pre-release** version of DevBuddy. It contains experimental features and may have bugs.
+            This is a **${{ github.event.inputs.prereleaseType }}** pre-release of DevBuddy from the `${{ github.event.inputs.branch }}` branch.
 
-            > **Note:** Pre-releases use even minor versions (0.10.x, 0.12.x). Stable releases use odd minor versions (0.9.x, 0.11.x).
+            > **Branch:** `${{ github.event.inputs.branch }}`
+            > **Type:** ${{ github.event.inputs.prereleaseType }}
+            > **Published to Marketplace:** ${{ github.event.inputs.skipMarketplace == 'yes' && 'No (GitHub only)' || 'Yes' }}
 
             ### ⚠️ Important Notes
 
             - This version is for testing purposes only
+            - ${{ github.event.inputs.branch != 'main' && 'This is an **experimental** build from a non-main branch' || 'This is a standard pre-release from main' }}
             - Use at your own risk in production environments
             - Report any issues on [GitHub Issues](https://github.com/${{ github.repository }}/issues)
 
@@ -155,7 +218,7 @@ jobs:
             3. Search for "DevBuddy"
             4. Click the dropdown next to "Install" and select **"Install Pre-Release Version"**
 
-            **Option 2: Manual Installation**
+            **Option 2: Manual Installation (Download below)**
             Download the `.vsix` file below and install it:
 
             ```bash
@@ -167,6 +230,7 @@ jobs:
             Please report any bugs or issues you encounter:
             - [Create an issue](https://github.com/${{ github.repository }}/issues/new)
             - Include the version number: `${{ steps.version.outputs.new_version }}`
+            - Include the branch: `${{ github.event.inputs.branch }}`
             - Describe what you were doing when the issue occurred
 
             ---
@@ -183,19 +247,31 @@ jobs:
           echo "## 🧪 Pre-release Published!" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "**Version:** v${{ steps.version.outputs.new_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Branch:** ${{ github.event.inputs.branch }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Type:** ${{ github.event.inputs.prereleaseType }}" >> $GITHUB_STEP_SUMMARY
           echo "**VSIX:** ${{ steps.vsix.outputs.filename }}" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "### Versioning Strategy:" >> $GITHUB_STEP_SUMMARY
-          echo "- Pre-releases: even minor versions (0.10.x, 0.12.x)" >> $GITHUB_STEP_SUMMARY
-          echo "- Stable releases: odd minor versions (0.9.x, 0.11.x)" >> $GITHUB_STEP_SUMMARY
+          if [ "${{ github.event.inputs.branch }}" = "main" ]; then
+            echo "- Pre-releases from main: even minor versions (0.10.x, 0.12.x)" >> $GITHUB_STEP_SUMMARY
+            echo "- Stable releases: odd minor versions (0.9.x, 0.11.x)" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- Experimental pre-releases include branch identifier in version" >> $GITHUB_STEP_SUMMARY
+            echo "- Format: X.Y.Z-${{ github.event.inputs.prereleaseType }}.N+branchid" >> $GITHUB_STEP_SUMMARY
+          fi
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "### Published to:" >> $GITHUB_STEP_SUMMARY
-          echo "- ✅ VS Code Marketplace (Pre-release channel)" >> $GITHUB_STEP_SUMMARY
+          if [ "${{ github.event.inputs.skipMarketplace }}" = "yes" ]; then
+            echo "- ⏭️ VS Code Marketplace (Skipped)" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "- ✅ VS Code Marketplace (Pre-release channel)" >> $GITHUB_STEP_SUMMARY
+          fi
           echo "- ✅ GitHub Releases (Pre-release)" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "### How users can install:" >> $GITHUB_STEP_SUMMARY
           echo "1. In VS Code, search for DevBuddy in Extensions" >> $GITHUB_STEP_SUMMARY
           echo "2. Click \"Install Pre-Release Version\"" >> $GITHUB_STEP_SUMMARY
+          echo "3. Or download the .vsix from the GitHub release" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "### Links:" >> $GITHUB_STEP_SUMMARY
           echo "- [Release page](https://github.com/${{ github.repository }}/releases/tag/v${{ steps.version.outputs.new_version }})" >> $GITHUB_STEP_SUMMARY
diff --git a/docs/developer/BETA_CHANNEL_GUIDE.md b/docs/developer/BETA_CHANNEL_GUIDE.md
index 4c399b8..92a816d 100644
--- a/docs/developer/BETA_CHANNEL_GUIDE.md
+++ b/docs/developer/BETA_CHANNEL_GUIDE.md
@@ -1,31 +1,106 @@
 # Beta Channel Guide
 
-This guide explains how to manage and publish beta/pre-release versions of DevBuddy.
+This guide explains how to manage and publish beta/pre-release versions of DevBuddy, including releases from experimental branches.
 
 ## Overview
 
 DevBuddy supports VS Code's built-in pre-release system, allowing users to opt-in to beta versions directly from the marketplace. Pre-release versions are published alongside stable versions and are clearly marked as such.
 
+### Key Features
+
+- **Release from any branch** - No need to merge to main first
+- **Multiple pre-release types** - alpha, beta, rc
+- **Branch-aware versioning** - Experimental branches include branch identifier
+- **Skip marketplace option** - GitHub-only releases for internal testing
+
 ## Pre-release Types
 
 We support three types of pre-release versions:
 
-- **alpha** (`X.Y.Z-alpha.N`) - Early development, experimental features, may be unstable
-- **beta** (`X.Y.Z-beta.N`) - Feature-complete but needs testing, relatively stable
-- **rc** (`X.Y.Z-rc.N`) - Release candidate, final testing before stable release
+| Type | Use Case | Stability |
+|------|----------|-----------|
+| **alpha** | Early development, experimental features | May be unstable |
+| **beta** | Feature-complete but needs testing | Relatively stable |
+| **rc** | Release candidate, final testing | Should be stable |
 
-## Version Numbering
+## Releasing from Experimental Branches
+
+### Quick Start
+
+1. Create your experimental branch:
+   ```bash
+   git checkout -b experimental/my-feature
+   git push origin experimental/my-feature
+   ```
+
+2. Go to **Actions** → **"Publish Beta (Pre-release)"**
 
-Pre-release versions follow this format:
+3. Configure the release:
+   - **Branch to release from**: `experimental/my-feature`
+   - **Pre-release type**: `alpha` (recommended for experimental)
+   - **Increment patch**: `yes` (for subsequent releases)
+   - **Skip marketplace**: `yes` (optional - for internal testing only)
 
+4. Click **"Run workflow"**
+
+### Version Format
+
+**From main branch:**
+```
+0.10.0  (even minor = pre-release)
+0.11.0  (odd minor = stable)
+```
+
+**From experimental branches:**
 ```
-major.minor.patch-type.number
+0.8.3-alpha.1+myfeature
+0.8.3-alpha.2+myfeature
 ```
 
-Examples:
-- `0.6.0-beta.1` - First beta of version 0.6.0
-- `0.6.0-beta.2` - Second beta of version 0.6.0
-- `1.0.0-rc.1` - Release candidate for version 1.0.0
+The `+branchid` suffix identifies which branch the release came from.
+
+### CI Support
+
+CI automatically runs on these branch patterns:
+- `main`, `develop`
+- `experimental/**`, `experiment/**`, `exp/**`
+- `feature/**`, `feat/**`
+
+Example branch names that trigger CI:
+```bash
+experimental/new-feature
+experiment/refactor
+exp/bugfix
+feature/cool-thing
+feat/widget
+```
+
+## Workflow Options
+
+### Branch Selection
+
+Choose any branch that exists in the repository:
+- `main` - Standard pre-releases with even/odd versioning
+- `experimental/*` - Feature branches with branch identifier in version
+- Any other branch name
+
+### Pre-release Type
+
+- **alpha** - Recommended for experimental branches (highly experimental)
+- **beta** - For staging/testing branches (mostly stable)  
+- **rc** - For release candidates (should be stable)
+
+### Skip Marketplace
+
+When enabled:
+- ✅ Builds and packages the extension
+- ✅ Creates GitHub pre-release with VSIX download
+- ❌ Does NOT publish to VS Code Marketplace
+
+**Use cases:**
+- Internal team testing
+- Stakeholder demos
+- Testing before public pre-release
 
 ## Publishing Beta Versions
 
@@ -34,17 +109,21 @@ Examples:
 1. Go to **Actions** tab in GitHub
 2. Select **"Publish Beta (Pre-release)"** workflow
 3. Click **"Run workflow"**
-4. Choose:
+4. Choose options:
+   - **Branch**: The branch to release from
    - **Beta Type**: alpha, beta, or rc
-   - **Bump Type**: major, minor, or patch (for base version bump)
+   - **Increment Patch**: yes/no
+   - **Skip Marketplace**: yes/no
 5. Click **"Run workflow"**
 
 The workflow will:
-- Determine the next pre-release version
+- Checkout the specified branch
 - Build and test the extension
-- Publish to VS Code Marketplace as pre-release
-- Create a GitHub pre-release
+- Determine the next pre-release version
+- Publish to VS Code Marketplace (unless skipped)
+- Create a GitHub pre-release with VSIX
 - Tag the version in git
+- Push version bump back to the branch
 
 ### Option 2: Manual with Script
 
@@ -86,7 +165,7 @@ Then follow the instructions printed by the script to commit, tag, and push.
    # Creates: dev-buddy-0.6.0-beta.1.vsix
    ```
 
-4. **Publish to marketplace**:
+4. **Publish to marketplace** (optional):
    ```bash
    npm run beta:publish
    # Uses VSCE_PAT from environment
@@ -100,14 +179,6 @@ Then follow the instructions printed by the script to commit, tag, and push.
    git push origin HEAD --tags
    ```
 
-6. **Create GitHub pre-release**:
-   - Go to GitHub Releases
-   - Click "Draft a new release"
-   - Select the tag (v0.6.0-beta.1)
-   - Check "Set as a pre-release"
-   - Upload the .vsix file
-   - Publish
-
 ## Installing Beta Versions
 
 ### For End Users
@@ -122,7 +193,7 @@ Then follow the instructions printed by the script to commit, tag, and push.
 1. Download .vsix from GitHub pre-release
 2. Run:
    ```bash
-   code --install-extension dev-buddy-X.Y.Z-beta.N.vsix
+   code --install-extension dev-buddy-X.Y.Z-alpha.N.vsix
    ```
 
 **Switching Back to Stable**:
@@ -140,96 +211,152 @@ npm run compile && npm run compile:webview
 npm run package
 
 # Install in VS Code
-code --install-extension dev-buddy-X.Y.Z-beta.N.vsix
+code --install-extension dev-buddy-*.vsix
 
-# Or use the reinstall script (may need updating for beta)
+# Or use the reinstall script
 ./reinstall.sh
 ```
 
-## Beta Release Workflow
+## Experimental Branch Workflow
 
-### When to Create a Beta
+### Recommended Flow
 
-Create a beta version when:
-- Introducing new experimental features
-- Making significant architectural changes
-- Testing with a subset of users before stable release
-- Need feedback before finalizing a release
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. Create experimental branch from main                     │
+│    git checkout -b experimental/feature-name                │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 2. Develop and commit changes                               │
+│    git commit -m "feat: add awesome feature"                │
+│    git push origin experimental/feature-name                │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 3. CI runs automatically on push                            │
+│    ✅ Lint, type-check, build                               │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 4. Release alpha from experimental branch                   │
+│    Actions → Publish Beta → branch: experimental/feature    │
+│    Creates: 0.8.3-alpha.1+featurename                       │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 5. Test, iterate, release more alphas                       │
+│    0.8.3-alpha.2+featurename                                │
+│    0.8.3-alpha.3+featurename                                │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 6. When ready, merge to main and release stable             │
+│    PR → main → Release workflow → 0.9.0                     │
+└─────────────────────────────────────────────────────────────┘
+```
 
-### Beta Release Process
+### Example: Testing a Risky Feature
 
-1. **Development**:
-   - Develop feature on a feature branch
-   - Merge to `main` (or `beta` branch if you prefer)
+```bash
+# Start experimental branch
+git checkout -b experimental/risky-refactor
+git push origin experimental/risky-refactor
+
+# Make changes, push
+git add .
+git commit -m "refactor: major architecture change"
+git push
+
+# CI runs automatically ✅
+
+# Go to GitHub Actions
+# Run "Publish Beta (Pre-release)"
+# - Branch: experimental/risky-refactor
+# - Type: alpha
+# - Skip marketplace: yes (for internal testing)
 
-2. **Create Beta**:
-   - Run beta release workflow or script
-   - Test the beta locally first
+# Download VSIX from GitHub release
+# Test locally
 
-3. **Announce**:
-   - Share in Discord/Slack/GitHub Discussions
-   - Ask for feedback from beta testers
-   - Document known issues
+# If good, release to marketplace
+# Run again with Skip marketplace: no
 
-4. **Iterate**:
-   - Fix bugs found in beta
-   - Increment beta version (beta.2, beta.3, etc.)
-   - Publish updated betas as needed
+# If great, merge to main for stable release
+```
+
+## Version Numbering
 
-5. **Promote to Stable**:
-   - When ready, publish as stable release
-   - Update version to remove pre-release tag
-   - Use standard release workflow
+### From Main Branch
 
-### Example Beta Cycle
+Pre-release versions follow even/odd versioning:
 
 ```
-0.5.0 (current stable)
+0.9.0  (stable - odd minor)
   ↓
-0.6.0-beta.1 (initial beta)
+0.10.0 (pre-release - even minor)
   ↓ (bug fixes)
-0.6.0-beta.2
+0.10.1
   ↓ (more fixes)
-0.6.0-beta.3
-  ↓ (final testing)
-0.6.0-rc.1 (release candidate)
-  ↓ (approved)
-0.6.0 (stable release)
+0.10.2
+  ↓ (promoted to stable)
+0.11.0 (stable - odd minor)
+```
+
+### From Experimental Branches
+
+Experimental versions include branch identifier:
+
+```
+0.8.3  (current stable)
+  ↓
+0.8.3-alpha.1+myfeature (first experimental)
+  ↓
+0.8.3-alpha.2+myfeature (iteration)
+  ↓
+0.8.3-alpha.3+myfeature (more iteration)
+  ↓ (merge to main)
+0.9.0 (stable release with feature)
 ```
 
 ## Best Practices
 
+### Branch Naming
+
+Use descriptive prefixes:
+```bash
+experimental/ai-improvements
+experimental/jira-v2
+feature/dark-mode
+exp/performance-test
+```
+
 ### Version Strategy
 
 - Use **alpha** for highly experimental features
 - Use **beta** for features that need community testing
-- Use **rc** (release candidate) for final validation before stable
-- Keep betas short-lived (1-2 weeks max)
+- Use **rc** for final validation before stable
 
 ### Communication
 
-- Always announce beta releases in appropriate channels
-- Include changelog/release notes
+- Always announce experimental releases in appropriate channels
+- Include installation instructions
 - List known issues and limitations
 - Set expectations about stability
 
-### Testing
+### Testing Flow
 
-- Test beta versions thoroughly before publishing
-- Have a rollback plan (stable version available)
-- Monitor issues/feedback closely
-- Be responsive to beta tester reports
+1. **Internal testing** (Skip marketplace = yes)
+   - Build and release GitHub-only
+   - Test with team
+   
+2. **Public pre-release** (Skip marketplace = no)
+   - Release to marketplace pre-release channel
+   - Get community feedback
 
-### Transitioning to Stable
-
-When promoting a beta to stable:
-
-1. Create one final RC version if needed
-2. Test RC thoroughly
-3. If RC is good, remove pre-release tag
-4. Publish as stable using standard workflow
-5. Announce the stable release
-6. Update documentation
+3. **Stable release** (Merge to main)
+   - Create PR to main
+   - Run standard release workflow
 
 ## Marketplace Behavior
 
@@ -238,7 +365,7 @@ When promoting a beta to stable:
 - Users see a **"Switch to Pre-Release Version"** button
 - Pre-release versions auto-update to newer pre-releases
 - Users can switch back to stable anytime
-- Both versions can coexist on the marketplace
+- Both versions coexist on the marketplace
 
 ### Version Resolution
 
@@ -249,35 +376,44 @@ VS Code handles version selection:
 ### Version Display
 
 In the marketplace:
-- Stable: "DevBuddy v0.5.0"
-- Pre-release: "DevBuddy v0.6.0-beta.1 (Pre-release)"
+- Stable: "DevBuddy v0.9.0"
+- Pre-release: "DevBuddy v0.10.0 (Pre-release)"
+- Experimental: "DevBuddy v0.8.3-alpha.1+myfeature (Pre-release)"
 
 ## Troubleshooting
 
+### "Branch does not exist"
+
+**Problem**: Trying to release from a branch that doesn't exist remotely.
+
+**Solution**: Push your branch first:
+```bash
+git push origin your-branch-name
+```
+
 ### "Pre-release version is older than stable"
 
-This happens when stable version is newer than pre-release. Solutions:
-- Bump base version in beta (e.g., 0.6.0-beta.1 vs 0.5.0)
-- Publish a new beta with higher version number
+**Problem**: This happens when stable version is newer than pre-release.
+
+**Solution**:
+- Bump base version in your experimental branch
+- Or accept that marketplace will show stable as "latest"
 
-### "Users not seeing beta updates"
+### "Users not seeing experimental updates"
 
+**Solution**:
 - Ensure they clicked "Switch to Pre-Release Version"
 - Check they have auto-updates enabled
 - Verify marketplace shows the pre-release
+- For GitHub-only releases, share VSIX download link directly
 
 ### "Want to skip beta and go to stable"
 
-- Just publish stable version with higher version number
+**Solution**:
+- Merge your branch to main
+- Run stable release workflow
 - The marketplace will show stable as latest
 
-### "Need to unpublish a beta"
-
-You cannot unpublish from marketplace, but you can:
-- Publish a newer beta with fixes
-- Wait for stable release to supersede it
-- Mark it as deprecated in release notes
-
 ## GitHub Secrets Required
 
 For automated publishing, ensure these secrets are set:
@@ -326,9 +462,8 @@ If you encounter issues with the beta release process:
 1. Check the GitHub Actions logs
 2. Verify all secrets are set correctly
 3. Test the beta locally before publishing
-4. Reach out in Discord/GitHub Discussions
+4. Check branch exists and is pushed to remote
 
 ---
 
-**Remember:** Beta releases are for testing. Always maintain a stable version that users can fall back to!
-
+**Remember:** Experimental branches let you iterate freely without affecting main. Release early, release often, and gather feedback!