Refactor release workflow to verify package.json version against release tag and update documentation on version update process. Implemented a warning system for version mismatches and clarified the update-before-tagging approach in RELEASES.md. (#37)

Co-authored-by: DrakeNguyen <drake.ha.nguyen@gmail.com>

Author: drakehanguyen

.github/workflows/release.yml

@@ -185,42 +185,33 @@ jobs:
         id: deployment
         uses: actions/deploy-pages@v4
 
-      - name: Sync package.json version to main branch
+      - name: Verify package.json version matches tag
         if: success()
-        continue-on-error: true  # Don't fail the workflow if this step fails
+        continue-on-error: true
         run: |
           VERSION="${{ steps.tag_version.outputs.version }}"
+          TAG_NAME="${{ steps.tag_version.outputs.tag_name }}"
 
-          # Configure git
-          git config --local user.email "action@github.com"
-          git config --local user.name "GitHub Action"
-
-          # Fetch main branch and check it out
-          git fetch origin main
-          git checkout main
-
-          # Check if package.json needs updating
+          # Check version in package.json from the tag
           CURRENT_VERSION=$(node -p "require('./package.json').version")
+
           if [ "$CURRENT_VERSION" = "$VERSION" ]; then
-            echo "✅ package.json already has version $VERSION, no commit needed"
-            exit 0
+            echo "✅ package.json version ($CURRENT_VERSION) matches release tag ($TAG_NAME)"
+            echo "✅ Version sync verified - following Approach 1 (Update Before Tagging)"
+          else
+            echo "⚠️  WARNING: package.json version ($CURRENT_VERSION) does not match release tag ($TAG_NAME)"
+            echo ""
+            echo "📋 Recommended workflow (Approach 1):"
+            echo "   1. Update package.json version to $VERSION"
+            echo "   2. Commit and push (via PR if branch is protected)"
+            echo "   3. Then create the release tag"
+            echo ""
+            echo "💡 For this release, the tag was created but package.json is out of sync."
+            echo "   Please manually update package.json to $VERSION to keep them in sync."
+            echo ""
+            echo "⚠️  This is a warning only - the release will continue."
           fi
 
-          # Update package.json version
-          node -e "
-            const fs = require('fs');
-            const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
-            pkg.version = '$VERSION';
-            fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
-            console.log('Updated package.json version to', '$VERSION');
-          "
-
-          # Commit and push
-          git add package.json
-          git commit -m "chore: update version to $VERSION [skip ci]"
-          git push origin main
-          echo "✅ Committed and pushed updated package.json to main"
-
       - name: Upload build artifacts
         if: success()
         uses: actions/upload-artifact@v4

docs/RELEASES.md

@@ -25,6 +25,24 @@ Before creating a release, update:
    }
    ```
 
+### Version Update Workflow (Approach 1: Update Before Tagging)
+
+This project follows **Approach 1** (Update Before Tagging), the industry standard used by most open-source projects:
+
+**Workflow:**
+1. Update `package.json` version
+2. Commit and push (via PR if branch is protected)
+3. After PR is merged, create the release tag
+
+**Why this approach:**
+- ✅ Tag already includes correct version in package.json
+- ✅ No post-release sync needed
+- ✅ Clean git history
+- ✅ Works perfectly with protected branches
+- ✅ Industry standard (used by React, Next.js, etc.)
+
+**Important:** Always update `package.json` **before** creating the release tag. The workflow will verify version sync and warn if they don't match.
+
 2. **CHANGELOG.md**: Add release notes for the new version
    ```markdown
    ## [0.1.0] - 2026-01-05
@@ -46,16 +64,33 @@ Before creating a release, update:
    }
    ```
 
-### Step 2: Commit Changes
+### Step 2: Commit and Push Version Update
+
+**If your branch is protected (requires PR):**
+```bash
+# Create a branch for the version update
+git checkout -b chore/bump-version-to-0.1.0
+
+# Commit changes
+git add package.json CHANGELOG.md
+git commit -m "chore: bump version to 0.1.0"
+
+# Push and create PR
+git push origin chore/bump-version-to-0.1.0
+# Then create PR on GitHub and merge it
+```
 
+**If your branch is not protected:**
 ```bash
-git add package.json CHANGELOG.md next.config.js
+git add package.json CHANGELOG.md
 git commit -m "chore: bump version to 0.1.0"
 git push origin main
 ```
 
 ### Step 3: Create and Push Version Tag
 
+**Important:** Only create the tag **after** the version update PR is merged (or pushed if not protected).
+
 ```bash
 # Create annotated tag
 git tag -a v0.1.0 -m "Release version 0.1.0"
@@ -221,6 +256,32 @@ These are set automatically during the release build.
 2. Check workflow permissions
 3. Verify CHANGELOG.md exists and has the version section
 
+### Version Mismatch Warning
+
+If you see a warning that `package.json` version doesn't match the release tag:
+
+1. **This means**: The tag was created before `package.json` was updated
+2. **Solution**: Update `package.json` manually to match the tag:
+   ```bash
+   # Checkout main branch
+   git checkout main
+
+   # Update package.json version to match tag (e.g., 0.1.0)
+   # Edit package.json: "version": "0.1.0"
+
+   # Commit and push (via PR if branch is protected)
+   git add package.json
+   git commit -m "chore: update version to 0.1.0"
+   git push origin main  # or create PR
+   ```
+
+3. **Prevention**: Always follow the workflow:
+   - Update `package.json` first
+   - Commit and merge PR
+   - Then create the release tag
+
+4. **Note**: The workflow will continue successfully even if versions don't match (warning only), since the git tag is the source of truth for versioning.
+
 ### Build Artifacts
 
 Build artifacts are uploaded to GitHub Actions and kept for 30 days. You can download them from the workflow run.