refactor(release): use VERSION file as source of truth instead of automatic bumping

Changed release workflow from automated version bumping to manual VERSION control.

**Changes to prepare-release.sh:**
- Remove version bump type argument (patch/minor/major)
- Read VERSION file as-is instead of calculating new version
- Add semver validation for VERSION format
- Sync VERSION to package.json instead of bumping both
- Updated documentation to explain manual workflow
- Simplified: no longer writes to VERSION file, just reads it

**Changes to npm-release.yaml:**
- Remove workflow_dispatch inputs (version bump type selector)
- Update documentation to explain manual VERSION bumping
- Remove ${{ github.event.inputs.version }} parameter

**Developer workflow (new):**
1. Manually bump VERSION file (e.g., 0.4.0 → 0.4.1)
2. Update CHANGELOG-mceachen.md with changes
3. Commit: git commit -am "release: prepare v0.4.1"
4. Trigger npm-release.yaml workflow
5. Workflow syncs VERSION to package.json and publishes

**Rationale:**
- Single source of truth: "The version is whatever VERSION says"
- Prepare releases: Can update CHANGELOG for new version before triggering workflow
- Transparent: Version bumps are explicit, visible git commits
- Standard practice: Similar to Go modules, Rust crates, Python tools

This is more intuitive for future maintainers than having the version
magically calculated during workflow execution.

Author: mceachen

.github/workflows/npm-release.yaml

@@ -38,25 +38,21 @@ name: "npm Release"
 
 #
 # RELEASE FLOW:
-#   1. prepare-release: Creates a release branch, bumps VERSION/sqlite-vec.h/package.json
-#   2. build-*: All builds run from the release branch (with correct version baked in)
-#   3. publish-npm: Publishes to npm, then merges release branch to main on success
+#   1. Manually bump VERSION file and update CHANGELOG-mceachen.md on main
+#   2. prepare-release: Creates a release branch, syncs VERSION to sqlite-vec.h/package.json
+#   3. build-*: All builds run from the release branch (with correct version baked in)
+#   4. publish-npm: Publishes to npm, then merges release branch to main on success
 #
 # If any step fails, main is untouched and the release branch can be deleted.
 #
+# BEFORE TRIGGERING THIS WORKFLOW:
+#   - Bump VERSION file (e.g., 0.4.0 → 0.4.1)
+#   - Update CHANGELOG-mceachen.md with release notes
+#   - Commit to main: git commit -am "release: prepare v0.4.1"
+#
 
 on:
   workflow_dispatch:
-    inputs:
-      version:
-        description: "Version bump type"
-        required: false
-        type: choice
-        default: "patch"
-        options:
-          - patch
-          - minor
-          - major
 
 permissions:
   contents: read
@@ -86,7 +82,7 @@ jobs:
 
       - name: Prepare release branch
         id: prepare
-        run: ./scripts/prepare-release.sh ${{ github.event.inputs.version }}
+        run: ./scripts/prepare-release.sh
 
   build-linux-x64:
     needs: [prepare-release]

scripts/prepare-release.sh

@@ -65,43 +65,47 @@ if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
 fi
 
 # Create release branch
-BRANCH="release/v${NEW_VERSION}"
+BRANCH="release/v${VERSION}"
 git checkout -b "$BRANCH"
 
-# Update VERSION file
-echo "$NEW_VERSION" > VERSION
-
-# Regenerate sqlite-vec.h from template
+# Regenerate sqlite-vec.h from template (uses VERSION file)
 make sqlite-vec.h
 
-# Update package.json and package-lock.json
-npm version "$NEW_VERSION" --no-git-tag-version
+# Sync VERSION to package.json and package-lock.json
+npm version "$VERSION" --no-git-tag-version --allow-same-version
 npm install --package-lock-only
 
-# Commit all version changes
-git add VERSION sqlite-vec.h package.json package-lock.json
+# Commit version sync (VERSION should already be committed on main)
+git add sqlite-vec.h package.json package-lock.json
 
 if [[ -n "${DRY_RUN:-}" ]]; then
   echo ""
   echo "=== DRY RUN MODE ==="
-  echo "Would commit and push branch '$BRANCH' with version $NEW_VERSION"
+  echo "Would commit and push branch '$BRANCH' with version $VERSION"
   echo ""
-  echo "Files staged:"
+  echo "Files to be committed:"
   git diff --cached --name-only
   echo ""
   echo "To clean up:"
   echo "  git reset HEAD && git checkout -- . && git checkout main && git branch -D $BRANCH"
   exit 0
 fi
 
-git commit -S -m "release: v${NEW_VERSION}"
+# Only commit if there are changes (VERSION might already be synced)
+if ! git diff --cached --quiet; then
+  git commit -S -m "release: sync package.json to v${VERSION}"
+  echo "Committed package.json sync for v${VERSION}"
+else
+  echo "No changes to commit (package.json already synced)"
+fi
+
 git push origin "$BRANCH"
 
 # Output for GitHub Actions
 if [[ -n "${GITHUB_OUTPUT:-}" ]]; then
   echo "branch=$BRANCH" >> "$GITHUB_OUTPUT"
-  echo "version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+  echo "version=$VERSION" >> "$GITHUB_OUTPUT"
 fi
 
 echo "Release branch '$BRANCH' created and pushed."
-echo "Version: $NEW_VERSION"
+echo "Version: $VERSION"