| name | release-prep |
| description | Prepare a @toolbox-web library for release AND drive release-please versioning. Covers the pre-release checklist (lint, test, build, bundle size, CHANGELOG, docs) PLUS release-please version operations — graduating a prerelease to GA (rc → stable), switching the prerelease identifier (beta → rc), and the per-package path-scoped Release-As bootstrap commits. Use when cutting a release, promoting a prerelease line to stable, or whenever release-please proposes the wrong version (e.g. an rc/patch bump when you expect the clean GA version like 3.0.0). |
| argument-hint | optional library name |
Release Preparation
Run the full pre-release checklist for a @toolbox-web library.
How to Use This Checklist
The checklist has 10 steps grouped into four phases. Complete each phase fully before starting the next; do not interleave phases. Within a phase, run the steps in order.
| Phase | Steps | Goal |
|---|
| Quality gates | 1 | Lint, test, and build the workspace cleanly. |
| Release validation | 2–4 | Bundle budget, CHANGELOG, breaking-change review. |
| Documentation | 5–7 | Docs updates, docs-site build, demo smoke test. |
| Commit hygiene | 8 | Final commit polish before merging. |
Handling Failures During the Checklist
If any command in steps 1–7 fails (lint error, failing test, type error, build break, bundle over budget, broken docs build, broken demo):
- Stop the checklist immediately — do not move to the next step. The release is not ready.
- Diagnose the failure by reading the actual command output. Do not retry the same command unchanged hoping for a different result.
- Fix the underlying cause in code, tests, or docs (per the standard delivery workflow). For bundle-budget failures, follow the
bundle-check skill's investigation checklist.
- Re-run only the failing command to confirm it now passes.
- Restart the checklist from step 1 so any fix that could have ripple effects (e.g. a code change that affects bundle size, or a doc change that breaks the docs build) is re-validated end-to-end.
- If the failure is a known intermittent or environmental issue (e.g. flaky test, transient network failure on docs build), document the cause and the rerun outcome in the release PR description rather than silently re-running.
Do not proceed to the Release Process section until every checklist step has passed cleanly in a single uninterrupted run.
Pre-Release Checklist
1. Lint, Test & Build All Projects (parallel)
Run all three quality gates across the workspace in a single parallel command. Nx parallelizes the targets, prefixes each output line with its project, and returns one exit code plus an explicit Failed tasks: list — so you get the speedup and still collect real per-target results:
bun nx run-many -t lint test build
This covers grid, grid-angular, grid-react, and grid-vue. All targets must pass:
- Lint — fix any errors. Do not skip warnings either — either fix them, or suppress with justification, which means add a single-line ESLint disable directive on the offending line that includes the rule name and a brief reason, e.g.
// eslint-disable-next-line @typescript-eslint/no-explicit-any -- third-party API returns any``. Bare eslint-disabledirectives without a-- reason are not acceptable.
- Test — all tests must pass across grid, grid-angular, grid-react, and grid-vue.
- Build — verify clean builds with no TypeScript errors. The build target hard-enforces the bundle budget (see step 2).
Do not pipe this command through | tail/| head/2>&1 on this machine — it hangs the terminal. Let the tool capture output, then read the captured file if the output is large.
2. Check Bundle Size Budget
Step 1's build already hard-enforces the budget via the Vite bundleBudget plugin (build fails if dist/libs/grid/index.js exceeds 170 kB raw or 50 kB gzipped). To read the exact raw/gzip sizes for every entry deterministically, run the shared report script:
bun run tools/build-size-report.ts
Confirm the core (index.js) grid cell is within budget (≤ 170 kB raw, ≤ 50 kB gzipped; soft warning at 45 kB gzipped). For a soft-warning or over-budget result, follow the bundle-check skill's investigation checklist.
3. Review CHANGELOG
Check libs/grid/CHANGELOG.md (and other library CHANGELOGs):
- New features documented with clear descriptions
- Bug fixes listed with issue references where available
- Breaking changes clearly marked with migration guides
- Entries follow Conventional Commits format
4. Check for Breaking Changes
Review all changes since last release:
git --no-pager log --oneline $(git describe --tags --abbrev=0)..HEAD
What constitutes a breaking change:
- Removed/renamed exports from
public.ts
- Changed method signatures (added required params, changed return types)
- Removed/renamed public properties/methods on
<tbw-grid>
- Removed/renamed CSS custom properties
- Changed event names or payload structures
- Removed/renamed plugin hook methods in
BaseGridPlugin
- Changed the
disconnectSignal contract (plugins depend on it for cleanup)
What is NOT a breaking change:
- Adding new optional properties, methods, or events
- Internal refactoring that doesn't affect public API
- Bug fixes (even if they change incorrect behavior)
- Adding new exports to
public.ts
- Performance improvements
- New plugins or plugin features
If breaking changes exist:
- Document in CHANGELOG with migration guide
- Ensure major version bump
- Consider deprecation warnings before removal
5. Update Documentation
Check if these files need updates:
| File | Update When |
|---|
libs/grid/README.md | New features, API changes |
| Plugin READMEs | Plugin changes |
apps/docs/src/content/docs/grid/**/*.mdx | Theming, API, getting started changes |
llms.txt | Public API, plugins, events, CSS vars changed |
llms-full.txt | Full AI guide needs updating |
.github/copilot-instructions.md | Workflow or conventions changed |
6. Verify Docs Site Builds
bun nx build docs
Docs site must build without errors.
7. Test Demo Applications
bun nx serve demo-vanilla
bun nx serve demo-angular
bun nx serve demo-react
Manually verify demos work with the latest changes.
8. Final Commit Hygiene
- All commits follow Conventional Commits format:
type(scope): description
- No WIP commits in the release branch
- Squash or rebase if needed for clean history
Release Process
This project uses release-please for automated releases:
- Configuration in
release-please-config.json
- Merging to main triggers release PR generation
- Approving the release PR publishes to npm
Switching the prerelease identifier (e.g. beta → rc) for a new major
Changing prerelease-type in release-please-config.json does NOT relabel an
in-progress prerelease line — while already on X.Y.Z-beta.N release-please only
increments the existing identifier (beta.4 → beta.5), ignoring the new type.
To jump the identifier (or seed a fresh major's prerelease), push a one-time,
per-package, path-scoped Release-As commit — attribution is by the file
paths the commit changes, not the commit scope:
printf '\n' >> libs/grid/CHANGELOG.md
git add libs/grid/CHANGELOG.md
git commit -m "chore(grid): bootstrap rc line" -m "Release-As: 3.0.0-rc.0"
printf '\n' >> libs/grid-angular/CHANGELOG.md
printf '\n' >> libs/grid-react/CHANGELOG.md
printf '\n' >> libs/grid-vue/CHANGELOG.md
git add libs/grid-angular/CHANGELOG.md libs/grid-react/CHANGELOG.md libs/grid-vue/CHANGELOG.md
git commit -m "chore(adapters): bootstrap rc line" -m "Release-As: 2.0.0-rc.0"
After the bootstrap tag exists, release-please auto-increments the new identifier
(rc.1, rc.2…) — no further Release-As needed. Verify the regenerated PR
bumps only the intended packages before merging. Full rationale + the trap that
once forced adapters to 3.0.0-rc.0: .github/knowledge/build-and-deploy.md
(release section).
Graduating a prerelease to the stable (GA) release
Same bootstrap applies when promoting X.Y.Z-rc.N → X.Y.Z. Flipping the config
alone does not deterministically land the clean GA version: the last tag is a
prerelease, so any pending feat/fix in range makes release-please carry the
rc identifier forward and bump within it — e.g. it proposed 3.0.1-rc.1 instead
of 3.0.0. Do both:
-
In release-please-config.json on main: set the branch "prerelease": false
(or drop prerelease/prerelease-type) and remove "versioning": "prerelease",
"prerelease": true, "prerelease-type" from each package.
-
Push per-package, path-scoped Release-As commits (verified recipe — grid to
3.0.0, adapters to 2.0.0; separate commits because one Release-As value is
written to EVERY package the commit touches, so a path-less/empty commit would
force all four to the same version):
printf '\n' >> libs/grid/CHANGELOG.md
git add libs/grid/CHANGELOG.md
git commit -m "chore(grid): graduate to stable 3.0.0" -m "Release-As: 3.0.0"
printf '\n' >> libs/grid-angular/CHANGELOG.md
printf '\n' >> libs/grid-react/CHANGELOG.md
printf '\n' >> libs/grid-vue/CHANGELOG.md
git add libs/grid-angular/CHANGELOG.md libs/grid-react/CHANGELOG.md libs/grid-vue/CHANGELOG.md
git commit -m "chore(adapters): graduate to stable 2.0.0" -m "Release-As: 2.0.0"
The trailing-newline on each package's CHANGELOG.md is a harmless routing
anchor (release-please prepends its section, so it never conflicts). After the
3.0.0/2.0.0 tags exist, release-please resumes normal semver (feat→minor,
fix→patch) — no more Release-As. Verify the regenerated release PR bumps
grid to exactly 3.0.0 and the adapters to 2.0.0 (and nothing else) before
merging.
Also flip the GA-only docs-deploy items in the same window so main stable
releases publish toolboxjs.com docs: the ci.yml build-docs/deploy-pages gate
- the
github-pages environment branch policy (2.x → main). No npm dist-tag /
LTS move is needed — this project does not maintain an LTS line on previous
majors: once GA publishes (version has no -) it auto-takes the latest dist-tag,
and the old major simply stops receiving releases. Details:
.github/knowledge/build-and-deploy.md (release section).
Post-Release
- Verify npm packages published correctly
- Check that GitHub release notes are accurate
- Update any external documentation or announcements
