shakapacker 8.4.0 → 9.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ccbba3c39a550ae683e13c45e3ac4f79733ae6ffebabf2d6ab55f37b7427d99
-  data.tar.gz: 569998bb9475e8ed2b8ba786d1ccdf2b84d562d61ba8ef78d08ad195c3ea2230
+  metadata.gz: 518eb8673a021c5e18507ebc14ba593128288ddb9f735390581bd998d1f33715
+  data.tar.gz: 3c2c532321d8c79e4374fbbe0854319d6ebd89df33557e21a4ce6e4ec322cc7c
 SHA512:
-  metadata.gz: 2c529d5f970394ca40b79d7ac1ddb430c197cbd508bf533195f13d81937cca872232436bcb92c5a8f38eafc9968ef0d1a82c280120545e421d143dcf72d12f0c
-  data.tar.gz: b341f56e92124b2418b56483dab20374aee03fca5de1e946e5b09ce1f2ca7d0daa16c47ed365a90f51a8f5bdf55235dbe9107cf95dc0a3b9b00e19056f72f343
+  metadata.gz: 26414fbf14fe2d835262ee5a6d2b46a9e50c76eee0391a0d859b60ee60f8899a87fa0e8c9d39aa651a8eadecb37639cd9684e775dd2004a55f83bb1f8aa4647e
+  data.tar.gz: 13f248afecdaa3ef579a20f7abf7ed592db788c2e5aa6b119a4940429b1e3c6f0bae263b985abe78e6ed0217116c6eeb9483c252f3a38bddd33e1c6e4533cc2c

data/.claude/commands/address-review.md

@@ -0,0 +1,206 @@
+---
+description: Fetch GitHub PR review comments, triage them, create todos for must-fix items, reply to comments, and resolve addressed threads
+---
+
+Fetch review comments from a GitHub PR in this repository, triage them, and create a todo list only for items worth addressing.
+
+# Instructions
+
+## Step 1: Determine the Repository
+
+```bash
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+```
+
+If this command fails, ensure `gh` CLI is installed and authenticated (`gh auth status`).
+
+## Step 2: Parse User Input
+
+Extract the PR number and optional review/comment ID from the user's message:
+
+**Supported formats:**
+
+- PR number only: `12345`
+- PR URL: `https://github.com/org/repo/pull/12345`
+- Specific PR review: `https://github.com/org/repo/pull/12345#pullrequestreview-123456789`
+- Specific issue comment: `https://github.com/org/repo/pull/12345#issuecomment-123456789`
+
+**URL parsing:**
+
+- Extract org/repo from URL path: `github.com/{org}/{repo}/pull/{PR_NUMBER}`
+- Extract fragment ID after `#` (e.g., `pullrequestreview-123456789` → `123456789`)
+- If a full GitHub URL is provided, use the org/repo from the URL instead of the current repo
+
+## Step 3: Fetch Review Comments
+
+**If a specific issue comment ID is provided (`#issuecomment-...`):**
+
+```bash
+gh api repos/${REPO}/issues/comments/{COMMENT_ID} | jq '{body: .body, user: .user.login, html_url: .html_url}'
+```
+
+**If a specific review ID is provided (`#pullrequestreview-...`):**
+
+```bash
+gh api repos/${REPO}/pulls/{PR_NUMBER}/reviews/{REVIEW_ID}/comments | jq '[.[] | {id: .id, path: .path, body: .body, line: .line, start_line: .start_line, user: .user.login}]'
+```
+
+**If only PR number is provided (fetch all PR review comments):**
+
+```bash
+gh api repos/${REPO}/pulls/{PR_NUMBER}/comments | jq '[.[] | {id: .id, path: .path, body: .body, line: .line, start_line: .start_line, user: .user.login, in_reply_to_id: .in_reply_to_id}]'
+```
+
+**Filtering comments:**
+
+- Skip comments where `in_reply_to_id` is set (these are replies, not top-level comments)
+- Do not skip bot-generated comments by default. Many actionable review comments in this repository come from bots.
+- Deduplicate repeated bot comments and skip bot status posts, summaries, and acknowledgments that do not require a code or documentation change
+- Treat as actionable by default only: correctness bugs, regressions, missing tests, and clear inconsistencies with adjacent code
+- Treat as non-actionable by default: style nits, speculative suggestions, changelog wording, duplicate bot comments, and "could consider" feedback unless the user explicitly asks for polish work
+- Focus on actionable feedback, not acknowledgments or thank-you messages
+
+**Error handling:**
+
+- If the API returns 404, the PR/comment doesn't exist - inform the user
+- If the API returns 403, check authentication with `gh auth status`
+- If the response is empty, inform the user no review comments were found
+
+## Step 4: Triage Comments
+
+Before creating any todos, classify every review comment into one of three categories:
+
+- `MUST-FIX`: correctness bugs, regressions, security issues, missing tests that could hide a real bug, and clear inconsistencies with adjacent code that would likely block merge
+- `DISCUSS`: reasonable suggestions that expand scope, architectural opinions that are not clearly right or wrong, and comments where the reviewer claim may be correct but needs a user decision
+- `SKIPPED`: style preferences, documentation nits, comment requests, test-shape preferences, speculative suggestions, changelog wording, duplicate comments, status posts, summaries, and factually incorrect suggestions
+
+Triage rules:
+
+- Deduplicate overlapping comments before classifying them. Keep one representative item for the underlying issue.
+- Verify factual claims locally before classifying a comment as `MUST-FIX`.
+- If a claim appears wrong, classify it as `SKIPPED` and note briefly why.
+- Preserve the original review comment ID and thread ID when available so the command can reply to the correct place and resolve the correct thread later.
+
+## Step 5: Create Todo List
+
+Create a todo list with TodoWrite containing **only the `MUST-FIX` items**:
+
+- One todo per must-fix comment or deduplicated issue
+- For file-specific comments: `"{file}:{line} - {comment_summary} (@{username})"` (content)
+- For general comments: Parse the comment body and extract the must-fix action
+- Format activeForm: `"Addressing {brief description}"`
+- All todos should start with status: `"pending"`
+
+## Step 6: Present Triage to User
+
+Present the triage to the user - **DO NOT automatically start addressing items**:
+
+- `MUST-FIX ({count})`: list the todos created
+- `DISCUSS ({count})`: list items needing user choice, with a short reason
+- `SKIPPED ({count})`: list skipped comments with a short reason, including duplicates and factually incorrect suggestions
+- Wait for the user to tell you which items to address
+- Always offer an explicit optional follow-up to post rationale replies on selected `SKIPPED` or declined `DISCUSS` items
+- Never post those rationale replies unless the user explicitly selects which items to reply to
+- Ask two things when relevant:
+  - Which items to address in code/tests/docs
+  - Which skipped/declined items (if any) should receive a rationale reply
+
+## Step 7: Address Items, Reply, and Resolve
+
+When addressing items, after completing each selected todo item, reply to the original review comment explaining how it was addressed.
+If the user selects skipped/declined items for rationale replies, post those replies too.
+
+**For issue comments (general PR comments):**
+
+```bash
+gh api repos/${REPO}/issues/{PR_NUMBER}/comments -X POST -f body="<response>"
+```
+
+**For PR review comments (file-specific, replying to a thread):**
+
+```bash
+gh api repos/${REPO}/pulls/{PR_NUMBER}/comments/{COMMENT_ID}/replies -X POST -f body="<response>"
+```
+
+**For standalone review comments (not in a thread):**
+
+```bash
+gh api repos/${REPO}/pulls/{PR_NUMBER}/comments -X POST -f body="<response>" -f commit_id="<COMMIT_SHA>" -f path="<FILE_PATH>" -f line=<LINE_NUMBER> -f side="RIGHT"
+```
+
+Note: `side` is required when using `line`. Use `"RIGHT"` for the PR commit side (most common) or `"LEFT"` for the base commit side.
+
+The response should briefly explain:
+
+- What was changed
+- Which commit(s) contain the fix
+- Any relevant details or decisions made
+
+After posting the reply, resolve the review thread when all of the following are true:
+
+- The comment belongs to a review thread and you have the thread ID
+- The concern was actually addressed in code, tests, or documentation, or it was explicitly declined with a clear explanation approved by the user
+- The thread is not already resolved
+
+Use GitHub GraphQL to resolve the thread:
+
+```bash
+gh api graphql -f query='mutation($threadId:ID!) { resolveReviewThread(input:{threadId:$threadId}) { thread { id isResolved } } }' -f threadId="<THREAD_ID>"
+```
+
+Do not resolve a thread if the fix is still pending, if you are unsure whether the reviewer concern is satisfied, or if the user asked to leave the thread open.
+
+If the user explicitly asks to close out a `DISCUSS` or `SKIPPED` item, reply with the rationale and resolve the thread only when the conversation is actually complete.
+
+# Example Usage
+
+```text
+/address-review https://github.com/org/repo/pull/12345#pullrequestreview-123456789
+/address-review https://github.com/org/repo/pull/12345#issuecomment-123456789
+/address-review 12345
+/address-review https://github.com/org/repo/pull/12345
+```
+
+# Example Output
+
+After fetching and triaging comments, present them like this:
+
+```text
+Found 5 review comments. Triage:
+
+MUST-FIX (1):
+1. ⬜ src/helper.rb:45 - Missing nil guard causes a crash on empty input (@reviewer1)
+
+DISCUSS (1):
+2. src/config.rb:12 - Extract this to a shared config constant (@reviewer1)
+   Reason: reasonable suggestion, but it expands scope
+
+SKIPPED (3):
+3. src/helper.rb:50 - "Consider adding a comment" (@claude[bot]) - documentation nit
+4. src/helper.rb:45 - Same nil guard issue (@greptile-apps[bot]) - duplicate of #1
+5. spec/helper_spec.rb:20 - "Consolidate assertions" (@claude[bot]) - test style preference
+
+Which items would you like me to address? (e.g., "1", "1,2", or "all must-fix")
+Optional: I can also post rationale replies for skipped/declined items (e.g., "reply 3,5" or "reply all skipped").
+```
+
+# Important Notes
+
+- Automatically detect the repository using `gh repo view` for the current working directory
+- If a GitHub URL is provided, extract the org/repo from the URL
+- Include file path and line number in each todo for easy navigation (when available)
+- Include the reviewer's username in the todo text
+- If a comment doesn't have a specific line number, note it as "general comment"
+- **NEVER automatically address all review comments** - always wait for user direction
+- When given a specific review URL, no need to ask for more information
+- **ALWAYS reply to comments after addressing them** to close the feedback loop
+- After triage, always offer to post rationale replies for selected `SKIPPED`/declined items, but only post them with explicit user approval
+- Resolve the review thread after replying when the concern is actually addressed and a thread ID is available
+- Default to real issues only. Do not spend a review cycle on optional polish unless the user explicitly asks for it
+- Triage comments before creating todos. Only `MUST-FIX` items should become todos by default
+- For large review comments (like detailed code reviews), parse and extract the actionable items into separate todos
+
+# Known Limitations
+
+- Rate limiting: GitHub API has rate limits; if you hit them, wait a few minutes
+- Private repos: Requires appropriate `gh` authentication scope

data/.claude/commands/update-changelog.md

@@ -0,0 +1,354 @@
+# Update Changelog
+
+You are helping to add an entry to the CHANGELOG.md file for the Shakapacker project.
+
+## Arguments
+
+This command accepts an optional argument: `$ARGUMENTS`
+
+- **No argument** (`/update-changelog`): Add entries to `[Unreleased]` without stamping a version header. Use this during development.
+- **`release`** (`/update-changelog release`): Add entries and stamp a version header. Auto-compute the next version based on changes (breaking → major, added features → minor, fixes → patch). Then `rake release` (with no args) will pick up this version automatically.
+- **`rc`** (`/update-changelog rc`): Same as `release`, but stamps an RC prerelease version (e.g., `v9.7.0-rc.0`). Auto-increments the RC index if prior RCs exist for the same base version.
+- **`beta`** (`/update-changelog beta`): Same as `rc`, but stamps a beta prerelease version (e.g., `v9.7.0-beta.0`).
+- **Explicit version** (`/update-changelog 9.7.0-rc.10` or `/update-changelog v9.7.0-rc.10`): Add entries and stamp the exact version provided. Skips auto-computation — use this when you already know the target version. The version string must use npm semver format with optional `-rc.N` or `-beta.N` suffix (e.g., `9.7.0-rc.10`, `9.7.0`). A `v` prefix is optional and will be added automatically if missing. If passed in RubyGems dot format (e.g., `9.7.0.rc.10` or `9.7.0.beta.2`), convert to npm semver dash format (`v9.7.0-rc.10` or `v9.7.0-beta.2`) for the changelog header.
+
+## When to Use This
+
+This command serves three use cases at different points in the release lifecycle:
+
+**During development** — Add entries to `[Unreleased]` as PRs merge:
+
+- Run `/update-changelog` to find merged PRs missing from the changelog
+- Entries accumulate under `## [Unreleased]`
+
+**Before a release** — Stamp a version header and prepare for release:
+
+- Run `/update-changelog release` (or `rc` or `beta`) to add entries AND stamp the version header
+- The version is auto-computed from changelog content (see "Auto-Computing the Next Version" below)
+- Commit and push CHANGELOG.md
+- Then run `rake release` (no args needed — it reads the version from CHANGELOG.md)
+- The release task automatically creates a GitHub release from the changelog section
+
+**After a release you forgot to update the changelog for** — Catch-up mode:
+
+- The command can retroactively find commits between tags and add missing entries
+- Ask the user whether to stamp a version header or add to `[Unreleased]`
+
+### Why changelog comes BEFORE the release
+
+- `release` automatically creates a GitHub release if a changelog section exists — no separate `sync_github_release` step needed
+- The release task warns if no changelog section is found for the target version
+- A premature version header (if release fails) is harmless — you'll release eventually
+- A missing changelog after release means GitHub release must be created manually
+
+## Auto-Computing the Next Version
+
+When stamping a version header (`release`, `rc`, or `beta`), compute the next version as follows:
+
+1. **Find the latest stable version tag** using semver sort:
+
+   ```bash
+   git tag -l 'v*' --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1
+   ```
+
+2. **Determine bump type from changelog content**:
+   - If changes include `### Breaking Changes` or `### ⚠️ Breaking Changes` → **major** bump
+   - If changes include `### Added` or `### New Features` → **minor** bump
+   - If changes only include `### Fixed`, `### Security`, `### Improved`, `### Changed`, `### Deprecated` → **patch** bump
+
+3. **Compute the version**:
+   - For `release`: Apply the bump to the latest stable tag (e.g., `9.5.0` + minor → `9.6.0`)
+   - For `rc`: Apply the bump, then find the next RC index based **only on git tags** (e.g., if `v9.6.0-rc.0` tag exists → `v9.6.0-rc.1`). **Do NOT use changelog headers** to determine the next index — a version header in the changelog is a draft that may not have been released yet. Only git tags represent shipped versions.
+   - For `beta`: Same as RC but with beta suffix
+
+4. **Verify**: Check that the computed version is newer than ALL existing tags (stable and prerelease). If not, ask the user what to do.
+
+5. **Show the computed version to the user and ask for confirmation** before stamping the header. If the bump type is ambiguous (e.g., changes could reasonably be classified as patch vs minor, or the changelog headings don't clearly signal the bump level), explain your reasoning for the suggested bump and ask the user to confirm or override before proceeding.
+
+## Critical Requirements
+
+1. **User-visible changes only**: Only add changelog entries for user-visible changes:
+   - New features
+   - Bug fixes
+   - Breaking changes
+   - Deprecations
+   - Performance improvements
+   - Security fixes
+   - Changes to public APIs or configuration options
+
+2. **Do NOT add entries for**:
+   - Linting fixes
+   - Code formatting
+   - Internal refactoring
+   - Test updates
+   - Documentation fixes (unless they fix incorrect docs about behavior)
+   - CI/CD changes
+
+## Formatting Requirements
+
+### Entry Format
+
+Each changelog entry MUST follow this exact format:
+
+```markdown
+- **Bold description of change**. [PR #123](https://github.com/shakacode/shakapacker/pull/123) by [username](https://github.com/username). Optional additional context or details.
+```
+
+**Important formatting rules**:
+
+- Start with a dash and space: `- `
+- Use **bold** for the main description
+- End the bold description with a period before the link
+- Always link to the PR: `[PR #123](https://github.com/shakacode/shakapacker/pull/123)` - **Note: Shakapacker uses `#` in PR links, unlike React on Rails**
+- Always link to the author: `by [username](https://github.com/username)`
+- End with a period after the author link
+- Additional details can be added after the main entry, using proper indentation for multi-line entries
+
+### Breaking Changes Format
+
+For breaking changes, use this format:
+
+```markdown
+- **Breaking**: Description of the breaking change. See [Migration Guide](docs/vX_upgrade.md) for migration instructions. [PR #123](https://github.com/shakacode/shakapacker/pull/123) by [username](https://github.com/username).
+```
+
+### Category Organization
+
+Entries should be organized under these section headings. The project uses both standard and custom headings:
+
+**Standard headings** (from keepachangelog.com) - use these for most changes:
+
+- `### Added` - New features
+- `### Changed` - Changes to existing functionality
+- `### Deprecated` - Deprecation notices
+- `### Removed` - Removed features
+- `### Fixed` - Bug fixes
+- `### Security` - Security-related changes
+- `### Improved` - Improvements to existing features
+
+**Custom headings** (project-specific) - use sparingly when standard headings don't fit:
+
+- `### ⚠️ Breaking Changes` - Breaking changes only (Shakapacker uses emoji in heading)
+- `### API Improvements` - API changes and improvements
+- `### Developer Experience` - Developer workflow improvements
+- `### Performance` - Performance improvements
+
+**Prefer standard headings.** Only use custom headings when the change needs more specific categorization.
+
+**Only include section headings that have entries.**
+
+### Version Header Format
+
+**Stable releases**: `## [v9.6.0] - March 7, 2026`
+
+**Prerelease versions** (RC and beta): Use npm semver format with dashes, NOT RubyGems dot format:
+
+- Correct: `## [v9.6.0-rc.1]` (npm semver — this is what `sync_github_release` expects)
+- Wrong: `## [v9.6.0.rc.1]` (RubyGems format — do NOT use this in CHANGELOG.md headers)
+
+This matters because the release rake tasks convert between formats:
+
+- Git tags use npm format: `v9.6.0-rc.1`
+- Gem versions use RubyGems format: `9.6.0.rc.1`
+- CHANGELOG.md headers must match git tag format: `## [v9.6.0-rc.1]`
+
+### Version Management
+
+After adding entries, use the rake task to manage version headers:
+
+```bash
+bundle exec rake update_changelog
+```
+
+This will:
+
+- Add headers for the new version
+- Update version diff links at the bottom of the file
+
+### Version Links
+
+After adding an entry to the `## [Unreleased]` section, ensure the version diff links at the bottom of the file are correct.
+
+**IMPORTANT**: Compare links at the bottom MUST use the `v` prefix to match git tags (e.g., `.../compare/v9.2.0...v9.3.0`). This is consistent with Shakapacker's changelog headers which also include the `v` prefix (e.g., `## [v9.3.0]`).
+
+The format at the bottom should be:
+
+```markdown
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.3.0...main
+[v9.3.0]: https://github.com/shakacode/shakapacker/compare/v9.2.0...v9.3.0
+```
+
+When a new version is released:
+
+1. Change `[Unreleased]` heading to `## [vX.Y.Z] - Month Day, Year`
+2. Add a new `## [Unreleased]` section at the top
+3. Update the `[Unreleased]` link to compare from the new version
+4. Add a new version link for the released version
+
+## Process
+
+### For Regular Changelog Updates
+
+#### Step 1: Fetch and read current state
+
+- **CRITICAL**: Run `git fetch origin main --tags` to ensure you have the latest commits AND tags
+- The workspace may be behind origin/main, causing you to miss recently merged PRs
+- After fetching, use `origin/main` for all comparisons, NOT local `main` branch
+- Read the current CHANGELOG.md to understand the existing structure
+
+#### Step 2: Reconcile tags with changelog sections (DO THIS FIRST)
+
+**This step catches missing version sections and is the #1 source of errors when skipped.**
+
+1. Get the latest git tag: `git tag -l 'v*' --sort=-v:refname | head -5`
+2. Get the most recent version header in CHANGELOG.md (the first `## [vVERSION]` after `## [Unreleased]`)
+3. **Compare them.** If the latest git tag does NOT appear anywhere in the changelog version headers, there are tagged releases missing from the changelog. **Important**: Don't just compare against the _top_ changelog header — a version header may exist _above_ the latest tag if it was stamped as a draft before tagging. Check whether the tag's version appears in _any_ `## [vX.Y.Z]` header. For example:
+   - Latest tag: `v9.6.0-rc.4`, and no `## [v9.6.0-rc.4]` header exists anywhere in CHANGELOG.md
+   - **Result: `v9.6.0-rc.4` is missing and needs its own section**
+   - But if `## [v9.7.0-rc.0]` is the top header (a draft, not yet tagged) and `## [v9.6.0-rc.4]` exists below it, then nothing is missing — the top header is simply a pre-release draft
+
+4. For EACH missing tagged version (there may be multiple):
+   a. Find commits in that tag vs the previous tag: `git log --oneline PREV_TAG..MISSING_TAG`
+   b. Extract PR numbers and fetch details for user-visible changes
+   c. Check which entries currently in `## [Unreleased]` actually belong to this tagged version (compare PR numbers against the commit list)
+   d. **Create a new version section** immediately before the previous version section
+   e. **Move** matching entries from Unreleased into the new section
+   f. **Add** any new entries for PRs in that tag that aren't in the changelog at all
+   g. **Update version diff links** at the bottom of the file
+
+5. Get the tag date with: `git log -1 --format="%Y-%m-%d" TAG_NAME`
+
+#### Step 3: Add new entries for post-tag commits
+
+1. Run `git log --oneline LATEST_TAG..origin/main` to find commits after the latest tag (LATEST_TAG is the most recent git tag, i.e., the same one identified in Step 2)
+2. **Extract ALL PR numbers** from commit messages: `git log --oneline LATEST_TAG..origin/main | grep -oE "#[0-9]+" | sort -u`
+3. If Step 2 found no missing tagged versions, verify no tag is ahead of main: `git log --oneline origin/main..LATEST_TAG` should be empty. If not, entries in "Unreleased" may belong to that tagged version — Step 2 should have caught this, so re-check.
+4. For each PR number, check if it's already in CHANGELOG.md: `grep "PR #XXX" CHANGELOG.md`
+5. For PRs not yet in the changelog:
+   - Get PR details: `gh pr view NUMBER --json title,body,author --repo shakacode/shakapacker`
+   - **Never ask the user for PR details** — get them from git history or the GitHub API
+   - Validate that the change is user-visible (per the criteria above). Skip CI, lint, refactoring, test-only changes.
+   - Add the entry to `## [Unreleased]` under the appropriate category heading
+
+#### Step 4: Stamp version header (only when a version mode or explicit version is given)
+
+If the user passed `release`, `rc`, `beta`, or an explicit version string as an argument:
+
+1. Auto-compute the next version (see "Auto-Computing the Next Version" above), or use the explicit version provided
+2. Insert the version header immediately after `## [Unreleased]`
+3. For `rc`/`beta` or an explicit prerelease version (e.g., `9.7.0-rc.10`): collapse prior prerelease sections of the same base version into the new section
+4. Update version diff links at the bottom of the file
+5. **Verify** the computed version looks correct
+
+If no argument was passed, skip this step — entries stay in `## [Unreleased]`.
+
+#### Step 5: Verify and finalize
+
+1. **Verify formatting**:
+   - Bold description with period
+   - Proper PR link (with `#` prefix for Shakapacker)
+   - Proper author link
+   - Consistent with existing entries
+   - File ends with a newline character
+   - **No duplicate section headings** (e.g., don't create two `### Fixed` sections — merge entries into the existing heading)
+2. **Verify version sections are in order** (Unreleased → newest tag → older tags)
+3. **Verify version diff links** at the bottom of the file are correct (compare links MUST use the `v` prefix to match git tags)
+4. **Run linting** after making changes:
+
+   ```bash
+   yarn lint
+   ```
+
+5. **Show the user** a summary of what was done:
+   - Which version sections were created
+   - Which entries were moved from Unreleased
+   - Which new entries were added
+   - Which PRs were skipped (and why)
+6. If in `release`/`rc`/`beta` mode or explicit-version mode, **automatically commit, push, and open a PR**:
+   - Verify the working tree only has `CHANGELOG.md` changes; if there are other uncommitted changes, warn the user and stop
+   - Verify the current branch is `main` (`git branch --show-current`); if not, warn the user and stop
+   - Create a feature branch (e.g., `changelog-v9.6.0-rc.1`)
+   - Stage only `CHANGELOG.md` (`git add CHANGELOG.md`) and commit with message `Update CHANGELOG.md for vX.Y.Z` (using the stamped version)
+   - Push and open a PR with the changelog diff as the body
+   - If the push or PR creation fails, the CHANGELOG is already stamped locally — fix the issue and retry manually
+   - Remind the user to run `bundle exec rake release` (no args) after merge to publish and auto-create the GitHub release
+
+### For Prerelease Versions (RC and Beta)
+
+When the user passes `rc` or `beta` as an argument (or when creating a prerelease section manually):
+
+1. **Find the latest tag** (stable or prerelease) using semver sort:
+
+   ```bash
+   git tag -l 'v*' --sort=-v:refname | head -10
+   ```
+
+2. **Auto-compute the next prerelease version** using the process in "Auto-Computing the Next Version" above.
+
+3. **Use npm semver format** for the version header:
+   - RC: `## [v9.6.0-rc.1]`
+   - Beta: `## [v9.6.0-beta.2]`
+
+4. **Always collapse prior prereleases into the current prerelease** (this is the default behavior):
+   - Combine all prior prerelease changelog entries into the new prerelease version section
+   - Remove previous prerelease version sections (e.g., remove `## [v9.6.0-rc.0]` when creating `## [v9.6.0-rc.1]`)
+   - When collapsing, **consolidate duplicate category headings** — if both the Unreleased section and a prior prerelease section have `### Fixed`, merge all entries under a single `### Fixed` heading
+   - **Remove orphaned version diff links** at the bottom of the file for collapsed prerelease sections
+   - Add any new user-visible changes from commits since the last prerelease
+   - Update version diff links to point from the last stable version to the new prerelease
+   - This keeps the changelog clean with a single prerelease section that accumulates all changes since the last stable release
+
+**Note**: The new version header must be inserted **immediately after `## [Unreleased]`** (see Step 4). This ensures correct ordering of version headers.
+
+### For Prerelease to Stable Version Release
+
+When releasing from prerelease to a stable version (e.g., v9.6.0-rc.1 → v9.6.0):
+
+1. **Remove all prerelease version labels** from the changelog:
+   - Change `## [v9.6.0-rc.0]`, `## [v9.6.0-rc.1]`, etc. to a single `## [v9.6.0]` section
+   - Also handle beta versions: `## [v9.6.0-beta.1]` etc.
+   - Combine all prerelease entries into the stable release section
+
+2. **Consolidate duplicate entries**:
+   - If bug fixes or changes were made to features introduced in earlier prereleases, keep only the final state
+   - Remove redundant changelog entries for fixes to prerelease features
+   - Keep the most recent/accurate description of each change
+
+3. **Update version diff links** at the bottom to point to the stable version
+
+## Examples
+
+Run this command to see real formatting examples from the codebase:
+
+```bash
+grep -A 3 "^### " CHANGELOG.md | head -30
+```
+
+### Good Entry Example
+
+```markdown
+- **Enhanced error handling for better security and debugging**. [PR #786](https://github.com/shakacode/shakapacker/pull/786) by [justin808](https://github.com/justin808).
+  - Path validation now properly reports permission errors instead of silently handling them
+  - Module loading errors now include original error context for easier troubleshooting
+  - Improved security by only catching ENOENT errors in path resolution, rethrowing permission and access errors
+```
+
+### Entry with Sub-bullets Example
+
+```markdown
+- **HTTP 103 Early Hints support** for faster asset loading. [PR #722](https://github.com/shakacode/shakapacker/pull/722) by [justin808](https://github.com/justin808). Automatically sends early hints when `early_hints: enabled: true` in `shakapacker.yml`. Works with `append_javascript_pack_tag`/`append_stylesheet_pack_tag`, supports per-controller/action configuration, and includes helpers like `configure_pack_early_hints` and `skip_send_pack_early_hints`. Requires Rails 5.2+ and HTTP/2-capable server. See [Early Hints Guide](docs/early_hints.md).
+```
+
+### Breaking Change Example
+
+```markdown
+- **Breaking: SWC default configuration now uses `loose: false`**. [PR #658](https://github.com/shakacode/shakapacker/pull/658) by [justin808](https://github.com/justin808). See [v9 Upgrade Guide - SWC Loose Mode](./docs/v9_upgrade.md#swc-loose-mode-breaking-change-v910) for migration details.
+```
+
+## Additional Notes
+
+- Keep descriptions concise but informative
+- Focus on the "what" and "why", not the "how"
+- Use past tense for the description
+- Be consistent with existing formatting in the changelog
+- Always ensure the file ends with a trailing newline

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,24 +1,21 @@
 ---
 name: Bug report
 about: Create a report for a crash or unexpected behavior.
-title: ''
+title: ""
 labels: bug
-assignees: ''
-
+assignees: ""
 ---
 
 _Notice: A bug is a crash or incorrect behavior. If you have a debugging or troubleshooting question, please open a discussion on the [Discussions Tab](https://github.com/shakacode/shakapacker/discussions). Otherwise, remove this line and fill out the following sections._
 
 ## Expected behavior:
 
-
 ## Actual behavior:
 
-
 ## Small, reproducible repo:
 
-
 ## Setup environment:
-- Ruby version: 
-- Rails version: 
-- Shakapacker version: 
+
+- Ruby version:
+- Rails version:
+- Shakapacker version:

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,21 +1,19 @@
 ---
 name: Feature request
 about: Create a request for new functionality
-title: ''
+title: ""
 labels: enhancement
-assignees: ''
-
+assignees: ""
 ---
 
 _Notice: A feature request describes a suggested improvement. If you have a debugging or troubleshooting question, please open a discussion on the [Discussions Tab](https://github.com/shakacode/shakapacker/discussions). Otherwise, remove this line and fill out the following sections._
 
 ## Desired behavior:
 
-
 ## Actual behavior:
 
-
 ## Setup environment:
-- Ruby version: 
-- Rails version: 
-- Shakapacker version: 
+
+- Ruby version:
+- Rails version:
+- Shakapacker version:

data/.github/STATUS.md

@@ -0,0 +1 @@
+# CI Status Update

data/.github/actionlint-matcher.json

@@ -0,0 +1,17 @@
+{
+  "problemMatcher": [
+    {
+      "owner": "actionlint",
+      "pattern": [
+        {
+          "regexp": "^(?:\\x1b\\[\\d+m)?(.+?)(?:\\x1b\\[\\d+m)*:(?:\\x1b\\[\\d+m)*(\\d+)(?:\\x1b\\[\\d+m)*:(?:\\x1b\\[\\d+m)*(\\d+)(?:\\x1b\\[\\d+m)*: (?:\\x1b\\[\\d+m)*(.+?)(?:\\x1b\\[\\d+m)* \\[(.+?)\\]$",
+          "file": 1,
+          "line": 2,
+          "column": 3,
+          "message": 4,
+          "code": 5
+        }
+      ]
+    }
+  ]
+}