|
| 1 | +--- |
| 2 | +name: bump-rspack-swc |
| 3 | +description: Upgrade the SWC Rust dependencies used by the Rspack repository, regenerate workspace version code, analyze the swc_core tag-to-tag changelog for breaking and Rspack-relevant changes, correlate fixes with Rspack issues, validate the upgrade, and commit, push, and open the GitHub pull request. Use when asked to bump, update, or upgrade swc_core or its aligned SWC crate versions in Rspack and prepare or submit the resulting PR. |
| 4 | +--- |
| 5 | + |
| 6 | +# Upgrade Rspack SWC |
| 7 | + |
| 8 | +Perform the upgrade end to end. Keep the patch focused, preserve unrelated work, and base every changelog claim on the SWC tag range. |
| 9 | + |
| 10 | +## Guardrails |
| 11 | + |
| 12 | +- Confirm the checkout is `web-infra-dev/rspack` and read the applicable `AGENTS.md` instructions before editing. |
| 13 | +- Inspect `git status --short`, the current branch, and remotes first. Never overwrite, discard, stage, or commit unrelated user changes. Stop for direction if unrelated changes overlap the files required by the upgrade. |
| 14 | +- Use exact, stable, non-yanked crate versions. Ignore prereleases unless the user explicitly requests one. |
| 15 | +- Treat the root `Cargo.toml` comment `Must be pinned with the same swc versions` as an invariant. Keep SWC direct dependencies on one compatible release set; do not blindly bump only `swc_core`. |
| 16 | +- Treat every `swc_experimental_*` crate as independent and out of scope. Never query, bump, or otherwise change its manifest or lockfile version as part of this workflow. |
| 17 | +- Keep existing `default-features`, feature lists, and unrelated dependency versions unchanged unless the new SWC release requires an adaptation. |
| 18 | +- Do not edit `crates/rspack_workspace/src/generated.rs` by hand. Generate it with `cargo codegen`. |
| 19 | +- Use official sources for release data: crates.io and `swc-project/swc` tags, commits, and pull requests. |
| 20 | +- Mention an upstream bug fix in the PR description only when it matches a Rspack issue's failure mode and the fix is validated when practical. Omit plausible, weak, or unverified bug connections instead of using “related” or “may fix”. |
| 21 | +- Use `pnpm run build:binding:dev` as the only validation command. Do not run tests or lint unless the user explicitly requests them. |
| 22 | +- Do not create the PR until the intended diff and required validation have been reviewed. If validation is incomplete or an important risk remains, explain it and open a draft only when the user still wants a PR. |
| 23 | + |
| 24 | +## 1. Establish the version range |
| 25 | + |
| 26 | +1. Read the SWC dependency block in the repository root `Cargo.toml` and record the exact current `swc_core` version as `OLD_VERSION`. |
| 27 | +2. Query crates.io for the newest stable, non-yanked `swc_core` release and record it as `NEW_VERSION`. Cross-check that the tag `swc_core@NEW_VERSION` exists in `https://github.com/swc-project/swc`. |
| 28 | +3. Stop with a no-op report if `OLD_VERSION` already equals `NEW_VERSION`. |
| 29 | +4. Enumerate the in-scope direct root dependencies named `swc` or beginning with `swc_`. At `swc_core@NEW_VERSION`, inspect the SWC workspace and crate manifests to identify their release-compatible versions. Also check crates.io for compatible patch releases published after the tag. |
| 30 | +5. Update only those in-scope entries in the root `Cargo.toml`. If the upgrade cannot resolve without changing an excluded dependency, stop and report the incompatibility instead of expanding scope. |
| 31 | +6. Refresh `Cargo.lock` through Cargo resolution, using a precise `swc_core` update where needed. Inspect resolution errors rather than loosening pins or features speculatively. |
| 32 | +7. Check the resolved SWC graph for unintended duplicate major versions, especially `swc_common`, AST, parser, transform, minifier, plugin, and HTML crates. Resolve incompatible direct pins before proceeding. |
| 33 | + |
| 34 | +Preserve full semantic versions for Cargo and tag operations. For the PR title labels, follow the recent Rspack SWC bump convention: use major-only labels for a major-to-major bump, otherwise use the shortest unambiguous semantic versions. |
| 35 | + |
| 36 | +## 2. Regenerate workspace code |
| 37 | + |
| 38 | +Run from the repository root: |
| 39 | + |
| 40 | +```bash |
| 41 | +cargo codegen |
| 42 | +``` |
| 43 | + |
| 44 | +Verify that `crates/rspack_workspace/src/generated.rs` contains `NEW_VERSION` in `rspack_swc_core_version()` and that no unrelated generated values changed. |
| 45 | + |
| 46 | +## 3. Build the tag-to-tag changelog |
| 47 | + |
| 48 | +Use these exact refs: |
| 49 | + |
| 50 | +```text |
| 51 | +swc_core@OLD_VERSION...swc_core@NEW_VERSION |
| 52 | +``` |
| 53 | + |
| 54 | +Create the canonical comparison link: |
| 55 | + |
| 56 | +```text |
| 57 | +https://github.com/swc-project/swc/compare/swc_core%40OLD_VERSION...swc_core%40NEW_VERSION |
| 58 | +``` |
| 59 | + |
| 60 | +Collect the complete commit list through the GitHub compare API or the exact tag refs in a temporary/local SWC checkout. Paginate and de-duplicate by SHA. If GitHub truncates a large comparison, split it across consecutive `swc_core@...` tags and merge the results. Do not substitute dates, branches, or release-page prose for the tag range. |
| 61 | + |
| 62 | +For commits that reference a pull request, inspect that PR’s title, body, labels, and relevant files. Drop release bookkeeping, dependency noise, and merges with no user-visible impact. Classify the remaining changes as: |
| 63 | + |
| 64 | +- breaking changes that require a Rspack adaptation or materially affect a Rspack integration surface; |
| 65 | +- new features available through a Rspack integration surface; |
| 66 | +- performance improvements that plausibly benefit Rspack; |
| 67 | +- bug fixes that match a verified Rspack issue. |
| 68 | + |
| 69 | +For every included item, link the upstream PR or commit and explain the concrete Rspack surface it affects. Search the Rspack checkout for changed SWC API names and behavior so the summary reflects actual integration points instead of repeating upstream titles. Omit changes with no meaningful Rspack impact. Do not add empty categories or state that there are no relevant changes. |
| 70 | + |
| 71 | +Search open and recent Rspack issues using the symptoms, syntax, transform names, and error text from notable SWC fixes. Read candidate issues and confirm the behavior matches from the available issue details, upstream fix, and local integration code. Do not run tests as part of this workflow. Record verified issue links for the PR. |
| 72 | + |
| 73 | +Keep issue correlation as an analysis step, not a reporting requirement. If no Rspack issue is verified, omit the bug fix and omit the related-links section entirely. Never list upstream bug fixes solely to summarize the SWC release. |
| 74 | + |
| 75 | +## 4. Adapt and validate |
| 76 | + |
| 77 | +Fix compilation changes caused by the new SWC release with the smallest compatible patch. Validate the upgrade by running only: |
| 78 | + |
| 79 | +```bash |
| 80 | +pnpm run build:binding:dev |
| 81 | +``` |
| 82 | + |
| 83 | +Do not run unit tests, integration tests, end-to-end tests, lint, or additional validation commands unless the user explicitly requests them. If the build fails because of the SWC upgrade, make the smallest necessary compatibility fix and rerun the same build command. If an environment failure prevents the build, capture the exact failure; never present it as passing. |
| 84 | + |
| 85 | +Review the final diff. Expected files are normally root `Cargo.toml`, `Cargo.lock`, and `crates/rspack_workspace/src/generated.rs`, plus only necessary compatibility changes. Confirm the generated version is correct and inspect the resolved SWC versions one final time. |
| 86 | + |
| 87 | +## 5. Commit and open the PR |
| 88 | + |
| 89 | +Use this exact title shape, retaining the backticks: |
| 90 | + |
| 91 | +```text |
| 92 | +chore: bump `swc_core` from FROM_LABEL to TO_LABEL |
| 93 | +``` |
| 94 | + |
| 95 | +Use the same subject for the commit unless repository history indicates a necessary commit-only variation. Stage only intended paths, review the staged diff, commit, push the current feature branch, and open the PR against `main`. |
| 96 | + |
| 97 | +Build the PR description from `.github/PULL_REQUEST_TEMPLATE.md`. Keep it brief and evidence-based: |
| 98 | + |
| 99 | +```markdown |
| 100 | +## Summary |
| 101 | + |
| 102 | +Bumps `swc_core` from `OLD_VERSION` to `NEW_VERSION` and aligns the compatible SWC dependency pins. |
| 103 | + |
| 104 | +[Upstream tag comparison](COMPARE_URL) |
| 105 | + |
| 106 | +- **Breaking:** <only Rspack-impacting breaking changes or required adaptations; omit when empty> |
| 107 | +- **Features:** <new capabilities available through Rspack; omit when empty> |
| 108 | +- **Performance:** <improvements likely to benefit Rspack; omit when empty> |
| 109 | +- **Fixes:** <only fixes matched to verified Rspack issues; omit when empty> |
| 110 | + |
| 111 | +## Related links |
| 112 | + |
| 113 | +<Include this section only when verified Rspack issue links exist. Use `Fixes #NNNN` only for confirmed fixes.> |
| 114 | + |
| 115 | +## Checklist |
| 116 | + |
| 117 | +- [x] Tests updated (or not required). |
| 118 | +- [x] Documentation updated (or not required). |
| 119 | + |
| 120 | +## Validation |
| 121 | + |
| 122 | +- `<exact command>` |
| 123 | +``` |
| 124 | + |
| 125 | +Include only useful changelog detail in the PR body; do not dump the raw commit list. Prefer omitting a low-confidence or low-impact item over making reviewers evaluate it. Remove empty optional bullets and sections from the final body. Mark a checklist item complete only when true, and state why tests or docs are not required when that is not obvious. After creation, report the PR URL, exact version range, changed files, validation results, and any remaining risks. |
0 commit comments