From fdc76f375cb5f20d0c64f9577fdcff656c35941c Mon Sep 17 00:00:00 2001
From: Charles Ouimet <charles.ouimet@gmail.com>
Date: Fri, 12 Jun 2026 21:25:08 -0400
Subject: [PATCH] [issues/646_start_new_release] Auto-create branch on
 release:start

## Summary

After publishing a release, `release:start` prepares the repo for the next development cycle by adding an `[Unreleased]` section to CHANGELOG and restoring the `[!IMPORTANT]` banner to README. Previously it did this in-place on whatever branch you were on. Now it detects when you are on `main` and creates a `post-release-v<VERSION>` branch first.

## Changes

- `start-release.sh`: added step 0 that checks the current branch. If on `main`, creates `post-release-v<VERSION>` and switches to it. Otherwise applies changes in-place.
- `CHANGELOG.md`: `[Unreleased]` section prepended (mechanical script output)
- `README.md`: `[!IMPORTANT]` banner restored (mechanical script output)

## Test Plan

- [x] All existing tests pass
- [ ] Manual: run `pnpm release:start:vscode-extension` from `main` and verify a branch is created

## Related

- Closes https://github.com/couimet/rangelink/issues/646
---
 packages/rangelink-vscode-extension/CHANGELOG.md   |  8 ++++++++
 packages/rangelink-vscode-extension/README.md      |  4 ++++
 .../scripts/start-release.sh                       | 14 ++++++++++++++
 3 files changed, 26 insertions(+)

diff --git a/packages/rangelink-vscode-extension/CHANGELOG.md b/packages/rangelink-vscode-extension/CHANGELOG.md
index 9e5d1ca2..f572c0ea 100644
--- a/packages/rangelink-vscode-extension/CHANGELOG.md
+++ b/packages/rangelink-vscode-extension/CHANGELOG.md
@@ -5,6 +5,14 @@ All notable changes to the RangeLink VS Code extension will be documented in thi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
 ## [2.0.0]
 
 ### Added
diff --git a/packages/rangelink-vscode-extension/README.md b/packages/rangelink-vscode-extension/README.md
index c92ea229..c0661c74 100644
--- a/packages/rangelink-vscode-extension/README.md
+++ b/packages/rangelink-vscode-extension/README.md
@@ -11,6 +11,10 @@
 > **"Claude Code today. Cursor AI tomorrow. Different shortcuts, different muscle memory."**<br />
 > **RangeLink ends it.** One keybinding. Any AI, any tool. Character-level precision. `recipes/baking/chickenpie.ts#L3C14-L314C16`
 
+> [!IMPORTANT]
+> This documentation is for the `main` branch and may include unreleased features marked with <sup>Unreleased</sup>.
+> Install the latest published version from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=couimet.rangelink-vscode-extension) or [Open VSX Registry](https://open-vsx.org/extension/couimet/rangelink-vscode-extension) (Cursor) for currently available features.
+
 ## Why RangeLink?
 
 Every AI coding assistant has its own way to share code — different shortcuts, different formats, different muscle memory. If you use multiple AI tools, you're constantly context-switching.
diff --git a/packages/rangelink-vscode-extension/scripts/start-release.sh b/packages/rangelink-vscode-extension/scripts/start-release.sh
index 7073bb7e..d3139320 100755
--- a/packages/rangelink-vscode-extension/scripts/start-release.sh
+++ b/packages/rangelink-vscode-extension/scripts/start-release.sh
@@ -7,6 +7,7 @@ set -euo pipefail
 # package.json. Idempotent — safe to re-run.
 #
 # Steps:
+#   0. If on main, create a post-release-v<VERSION> branch (otherwise apply in-place)
 #   1. Prepend [Unreleased] header with empty sections to CHANGELOG
 #   2. Re-add [!IMPORTANT] banner to README
 #
@@ -38,6 +39,19 @@ if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
   exit 1
 fi
 
+# --- Branch management ---
+
+CURRENT_BRANCH=$(git -C "$PACKAGE_DIR" rev-parse --abbrev-ref HEAD)
+MAIN_BRANCH=$(git -C "$PACKAGE_DIR" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo 'main')
+
+if [[ "$CURRENT_BRANCH" == "$MAIN_BRANCH" ]]; then
+  NEW_BRANCH="post-release-v${VERSION}"
+  echo -e "On ${MAIN_BRANCH} — creating branch ${GREEN}${NEW_BRANCH}${NC}"
+  git -C "$PACKAGE_DIR" checkout -b "$NEW_BRANCH"
+else
+  echo -e "${YELLOW}On branch ${CURRENT_BRANCH} — applying changes in-place.${NC}"
+fi
+
 # --- Prerequisites ---
 
 QA_YAML="$QA_DIR/qa-test-cases.yaml"