simplify release workflow and docs

- Streamline release.yml to essential steps only
- Remove complex changelog extraction (link instead)
- Simplify RELEASE_PREP.md to concise checklist
- One-click release: test → tag → publish → create release

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

Author: pftg

.github/workflows/release.yml

@@ -5,86 +5,58 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: 'Release version (e.g., 1.12.0)'
+        description: "Release version (e.g., 1.12.0)"
         required: true
         type: string
 
 jobs:
   release:
-    name: Release ${{ github.event.inputs.version }} to RubyGems.org
+    name: Release v${{ github.event.inputs.version }}
     runs-on: ubuntu-latest
 
     permissions:
-      id-token: write # Required for trusted publishing to RubyGems
-      contents: write # Required to create release tag
+      id-token: write
+      contents: write
 
     steps:
-      # Setup
       - uses: actions/checkout@v6
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
+      - uses: ruby/setup-ruby@v1
         with:
           bundler-cache: true
           ruby-version: ruby
 
-      # Verify version matches
       - name: Verify version
         run: |
           GEM_VERSION="${{ github.event.inputs.version }}"
-          RUBY_VERSION=$(ruby -rlib/capybara/screenshot/diff/version -e "puts Capybara::Screenshot::Diff::VERSION")
-          if [ "$GEM_VERSION" != "$RUBY_VERSION" ]; then
-            echo "❌ Version mismatch!"
-            echo "Input version: $GEM_VERSION"
-            echo "Ruby version: $RUBY_VERSION"
+          CODE_VERSION=$(ruby -rlib/capybara/screenshot/diff/version -e "puts Capybara::Screenshot::Diff::VERSION")
+          if [ "$GEM_VERSION" != "$CODE_VERSION" ]; then
+            echo "Version mismatch: input=$GEM_VERSION code=$CODE_VERSION"
             exit 1
           fi
-          echo "✅ Version verified: $GEM_VERSION"
 
-      # Build and test
-      - name: Run tests
+      - name: Test
         run: bundle exec rake test
 
-      # Build is handled by rubygems/release-gem@v1 during publish
-
-      # Create and push tag
-      - name: Create release tag
+      - name: Create tag
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-
-          TAG_NAME="v${{ github.event.inputs.version }}"
-
-          if git rev-parse "$TAG_NAME" >/dev/null 2>&1; then
-            echo "Tag $TAG_NAME already exists; skipping tag creation."
-          else
-            git tag -a "$TAG_NAME" -m "Release $TAG_NAME"
-            git push origin "$TAG_NAME"
-          fi
-          git tag -a "v${{ github.event.inputs.version }}" -m "Release v${{ github.event.inputs.version }}"
+          git tag -a "v${{ github.event.inputs.version }}" -m "v${{ github.event.inputs.version }}"
           git push origin "v${{ github.event.inputs.version }}"
 
-      # Publish to RubyGems
       - name: Publish to RubyGems
         uses: rubygems/release-gem@v1
 
-      # Create GitHub Release with changelog
-      - name: Extract changelog
-        run: |
-          VERSION="${{ github.event.inputs.version }}"
-          # Extract section for this version from CHANGELOG.md
-          awk "/^## \[v${VERSION}\]/,/^## \[v/" CHANGELOG.md | head -n -1 > RELEASE_NOTES.md
-          echo "## Changelog" >> RELEASE_NOTES.md
-          echo "" >> RELEASE_NOTES.md
-          echo "**Upgrade Guide:** See [docs/UPGRADING.md](https://github.com/${{ github.repository }}/blob/main/docs/UPGRADING.md) for detailed migration instructions." >> RELEASE_NOTES.md
-          cat RELEASE_NOTES.md
-
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
           tag_name: "v${{ github.event.inputs.version }}"
           name: "v${{ github.event.inputs.version }}"
-          body_path: RELEASE_NOTES.md
-          draft: false
-          generate_release_notes: false
+          body: |
+            ## What's Changed
+
+            See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md#v${{ github.event.inputs.version }}) for full details.
+
+            **Upgrade Guide:** [docs/UPGRADING.md](https://github.com/${{ github.repository }}/blob/main/docs/UPGRADING.md)
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/RELEASE_PREP.md

@@ -1,154 +1,50 @@
-# Release Preparation — v1.12.0 (Minor Release)
+# Release Preparation — v1.12.0
 
 ## Summary
-This release represents **71 commits** since v1.11.0 with significant new features, performance improvements, and behavior changes. As a minor release, it maintains backward compatibility while introducing powerful new capabilities.
 
-## Why Minor Version (v1.12.0)?
-
-### Behavior Changes (Non-Breaking)
-1. **SVN Support Removed** — Rarely used feature removed; no impact on Git users
-2. **Internal API Refactoring** — Private classes inlined; public API unchanged
-3. **Default Behavior Improvements**:
-   - `blur_active_element` now defaults to `true` (better screenshots)
-   - `hide_caret` now defaults to `true` (stable screenshots)
-   - `fail_if_new` now defaults to `true` in CI environments (safer pipelines)
-
-These changes improve the default experience without breaking existing configurations. Users who relied on the old defaults can explicitly override them.
-
-### New Features Worth Highlighting
-- HTML Reporter with interactive visual diff dashboard
-- Standalone image comparison via `Diff.compare`
-- Perceptual color distance (dE00) for anti-aliasing tolerance
-- `assert_no_screenshot_changes` DSL method
-- `Diff.configure` block helper for simplified setup
-- Ruby 3.5 support
-- Ruby 4.0 compatibility
-
-### Performance Improvements
-- Eliminated array allocations in ChunkyPNG shift-detection
-- Cached `without_tolerable_options?` at construction
-- Memoized `Difference#region_area_size`
-- Replaced method closures with blocks in BrowserHelpers
-
-### Dependency Changes
-- Removed ActiveSupport runtime dependency (lighter installations)
-- Updated all GitHub Actions to latest versions
-- Pinned minitest to < 6
+71 commits since v1.11.0 with new features, performance improvements, and default behavior changes.
 
 ## Release Checklist
 
-### Pre-Release Preparation
-
-- [x] Review CHANGELOG.md for accuracy
-- [x] Update version in `lib/capybara/screenshot/diff/version.rb` to `1.12.0`
-- [x] Run full test suite: `bundle exec rake test` (210 runs, 0 failures)
-- [ ] Run Docker tests: `bin/dtest` (optional, for thorough validation)
-- [ ] Re-record screenshot baselines if needed
-- [x] Commit changes: `git add CHANGELOG.md lib/capybara/screenshot/diff/version.rb docs/`
-- [x] Commit message: `chore: prepare v1.12.0 release`
-
-### Release via GitHub Actions (Recommended)
-
-This project uses GitHub Actions with trusted publishing to RubyGems.org.
-
-#### Step 1: Push Changes to GitHub
-
-```bash
-git push origin emdash/feat-re-review-git-history-8yi
-```
-
-#### Step 2: Create GitHub Release (Draft)
-
-1. Visit: https://github.com/donv/capybara-screenshot-diff/releases/new
-2. **Tag version:** `v1.12.0`
-3. **Release title:** `v1.12.0`
-4. **Description:** Copy content from `CHANGELOG.md` (the v1.12.0 section)
-5. **Add upgrade link:** Include link to `docs/UPGRADING.md`
-6. **Check:** ☑️ Set as a pre-release (optional, for review)
-7. Click **"Save draft"** or **"Publish release"**
-
-This will automatically create the git tag `v1.12.0`.
-
-#### Step 3: Trigger Release Workflow
-
-After publishing the GitHub Release, the release workflow will be available to run manually:
+### Pre-Release
 
-1. Visit: https://github.com/donv/capybara-screenshot-diff/actions/workflows/release.yml
-2. Click **"Run workflow"**
-3. Select the `v1.12.0` tag
-4. Click **"Run workflow"**
+- [x] Update version to `1.12.0`
+- [x] Run tests: `bundle exec rake test` (210 runs, 0 failures)
+- [x] Add CHANGELOG.md
+- [x] Add docs/UPGRADING.md
 
-The workflow will:
-- Build the gem
-- Publish to RubyGems.org using trusted publishing (no API key needed)
-- Push the release tag to the repository
+### Release (One Click)
 
-**Note:** The workflow requires `id-token: write` permission for trusted publishing and `contents: write` for tag management.
-
-### Alternative: Manual Release via Rake
-
-If you prefer manual release:
-
-```bash
-# Build the gem
-bundle exec rake build
-
-# Build and push to RubyGems (creates tag automatically)
-bundle exec rake release
-
-# This will:
-# 1. Create tag v1.12.0
-# 2. Build capybara-screenshot-diff-1.12.0.gem
-# 3. Push tag to origin
-# 4. Push gem to https://rubygems.org/
-```
+1. Push to GitHub
+2. Go to [Actions → Release](https://github.com/donv/capybara-screenshot-diff/actions/workflows/release.yml)
+3. Click **Run workflow**, enter `1.12.0`
+4. Workflow will: test → tag → publish to RubyGems → create GitHub Release
 
 ### Post-Release
 
-- [ ] Verify gem is available on RubyGems: https://rubygems.org/gems/capybara-screenshot-diff
-- [ ] Verify GitHub Release is published
-- [ ] Update CHANGELOG.md `[Unreleased]` link if needed
-- [ ] Announce release in relevant channels
-- [ ] Link to upgrade guide: `docs/UPGRADING.md`
-
-## Migration Guide for Users
-
-### What Users Need to Do
-
-1. **If using SVN**: Migrate to Git — SVN support has been removed (rare)
-2. **If relying on `blur_active_element` or `hide_caret` being `false` by default**: Explicitly set them to `false` in your configuration
-3. **If running in CI and want to allow new screenshots**: Set `fail_if_new = false` explicitly
-4. **If using ActiveSupport**: No longer required at runtime — can remove dependency if only used for this gem
-5. **If using internal APIs**: Most users unaffected — only private classes refactored
+- [ ] Verify on [RubyGems](https://rubygems.org/gems/capybara-screenshot-diff)
+- [ ] Verify GitHub Release created
 
-### What Works Out of the Box
+## What Changed
 
-- ✅ Zero-config setup still works
-- ✅ Existing screenshot comparisons continue to work
-- ✅ HTML reporter — just `require 'capybara_screenshot_diff/reporters/html'`
-- ✅ New perceptual color distance for better anti-aliasing handling
-- ✅ All public APIs remain compatible
-
-## Contributors
-
-Top contributors (by commit count) since v1.11.0:
-- Review with: `git log v1.11.0..HEAD --format="%an" | sort | uniq -c | sort -rn`
-
-## Statistics
-
-- **Total commits**: 71
-- **Features added**: 8
-- **Bugs fixed**: 15
-- **Performance improvements**: 4
-- **Refactoring commits**: 17
-- **Documentation improvements**: 8
-- **Build/CI updates**: 12
-- **Files changed**: Review with `git diff --stat v1.11.0..HEAD`
-
-## Next Steps
-
-1. Review this document
-2. Approve version bump to v1.12.0
-3. Run tests
-4. Tag and publish release
-5. Announce upgrade guide at `docs/UPGRADING.md`
+### New Features
+- HTML reporter with interactive dashboard
+- `Diff.compare` for standalone image comparison
+- Perceptual color distance (dE00) for anti-aliasing
+- `assert_no_screenshot_changes` DSL method
+- `Diff.configure` block helper
+- Ruby 3.5 & 4.0 support
+
+### Behavior Changes
+- `blur_active_element` defaults to `true`
+- `hide_caret` defaults to `true`
+- `fail_if_new` defaults to `true` in CI
+- SVN support removed
+- ActiveSupport no longer required
+
+### Performance
+- Faster ChunkyPNG shift-detection (eliminated allocations)
+- Cached computations in VIPS driver
+- Memoized region area size
+
+See [CHANGELOG.md](../CHANGELOG.md) for full details.