Update GitHub workflow and documentation for new versioning scheme

Co-authored-by: dibarbet <5749229+dibarbet@users.noreply.github.com>

Author: Copilot

.github/workflows/branch-snap.yml

@@ -1,6 +1,12 @@
 name: Branch snap
 on:
-  workflow_dispatch
+  workflow_dispatch:
+    inputs:
+      releaseCandidate:
+        description: 'Is this a release candidate snap from main? (Will increment main version to be higher than next stable release)'
+        required: false
+        default: 'false'
+        type: boolean
 
 permissions:
   contents: write
@@ -26,11 +32,42 @@ jobs:
       - name: Install dependencies 
         run: npm ci
       - name: Update version.json
-        run: npx gulp incrementVersion
+        run: |
+          if [ "${{ github.event.inputs.releaseCandidate }}" = "true" ]; then
+            npx gulp incrementVersion --releaseCandidate=true
+          else
+            npx gulp incrementVersion
+          fi
       - name: Create version update PR
         uses: peter-evans/create-pull-request@v4
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           commit-message: Update main version
           title: '[automated] Update main version'
           branch: merge/update-main-version
+
+  update-release-version:
+    needs: check-script
+    if: github.ref == 'refs/heads/prerelease'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out merge branch
+        uses: actions/checkout@v2
+        with:
+          ref: merge/prerelease-to-release
+          fetch-depth: 0
+      - name: Install NodeJS
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18.x'
+      - name: Install dependencies 
+        run: npm ci
+      - name: Update version.json for release
+        run: npx gulp updateVersionForRelease
+      - name: Commit and push version update
+        run: |
+          git config --local user.name "github-actions[bot]"
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git add version.json
+          git commit -m "Update version for stable release"
+          git push

CONTRIBUTING.md

@@ -196,15 +196,25 @@ More details for this are [here] (https://devdiv.visualstudio.com/DevDiv/_git/Vi
 ## Snapping for releases
 Extension releases on the marketplace are done from the prerelease and release branches (corresponding to the prerelease or release version of the extension).  Code flows from main -> prerelease -> release.  Every week we snap main -> prerelease.  Monthly, we snap prerelease -> release.
 
+### Versioning Scheme
+The extension follows a specific versioning scheme for releases:
+- **Prerelease versions**: Use standard minor version increments (e.g., 2.74, 2.75, 2.76...)
+- **Stable release versions**: Use the next tens version (e.g., 2.74 prerelease becomes 2.80 stable)
+- **Main branch after RC snap**: Jumps to one above the next stable version (e.g., if snapping 2.74 as RC, main becomes 2.81)
+
 ### Snap main -> prerelease
 The snap is done via the "Branch snap" github action.  To run the snap from main -> prerelease, run the action via "Run workflow" and choose main as the base branch.
 ![branch snap action](./docs/images/main_snap.png)
 
+When running the snap action, you can optionally check the "Is this a release candidate snap" checkbox. If checked:
+- The prerelease branch will receive the snapped code with the current version (e.g., 2.74)
+- The main branch version will be updated to be higher than the next stable release (e.g., 2.81, since the next stable would be 2.80)
+
 This will generate two PRs that must be merged.  One merging the main branch into prerelease, and the other bumps the version in main.
 ![generated prs](./docs/images/generated_prs.png)
 
 ### Snap prerelease -> release
-To snap from prerelease to release, run the same action but use **prerelease** as the workflow branch.  This will generate a single PR merging from prerelease to release.
+To snap from prerelease to release, run the same action but use **prerelease** as the workflow branch.  This will generate a PR merging from prerelease to release, and automatically update the version to the next stable release version (e.g., 2.74 -> 2.80) on the merge branch before the PR is merged.
 
 ### Marketplace release
 The marketplace release is managed by an internal AzDo pipeline.  On the pipeline page, hit run pipeline.  This will bring up the pipeline parameters to fill out: