nebu1eto/release

Release skill

This skill automates the release process for the SheetKit project. All releases are created from the main branch.

Prerequisites

Before starting a release:

1. Ensure you are on the main branch and it is up to date:

   git checkout main
   git pull origin main
   

2. Run the Rust verification suite:

   cargo build --workspace
   cargo test --workspace
   cargo clippy --workspace
   cargo fmt --check
   

3. Build the Node.js bindings and all workspace packages:

   pnpm -r build
   

4. Run Node.js lint and tests across the workspace:

   pnpm check
   pnpm -r test
   

   pnpm check runs Biome (linter + formatter). pnpm -r test runs Vitest for the Node.js binding tests.

Step 1: Bump versions

The version must be updated in all of the following files. Do not modify generated files (e.g., packages/sheetkit/index.js, packages/sheetkit/index.d.ts -- these are built from TypeScript sources).

Cargo workspace

In Cargo.toml (workspace root), update three version fields:

[workspace.package]
version = "X.Y.Z"

[workspace.dependencies]
sheetkit-xml = { version = "X.Y.Z", path = "crates/sheetkit-xml" }
sheetkit-core = { version = "X.Y.Z", path = "crates/sheetkit-core" }

Node.js native addon crate

In packages/sheetkit/Cargo.toml, update:

version = "X.Y.Z"

Node.js main package

In packages/sheetkit/package.json, update the top-level version and all 8 optional dependency versions:

{
  "version": "X.Y.Z",
  "optionalDependencies": {
    "@sheetkit/node-darwin-x64": "X.Y.Z",
    "@sheetkit/node-darwin-arm64": "X.Y.Z",
    "@sheetkit/node-win32-x64-msvc": "X.Y.Z",
    "@sheetkit/node-win32-arm64-msvc": "X.Y.Z",
    "@sheetkit/node-linux-x64-gnu": "X.Y.Z",
    "@sheetkit/node-linux-arm64-gnu": "X.Y.Z",
    "@sheetkit/node-linux-x64-musl": "X.Y.Z",
    "@sheetkit/node-linux-arm64-musl": "X.Y.Z"
  }
}

Platform-specific packages

Update "version" in each of the 8 platform package.json files:

• packages/darwin-arm64/package.json
• packages/darwin-x64/package.json
• packages/linux-arm64-gnu/package.json
• packages/linux-arm64-musl/package.json
• packages/linux-x64-gnu/package.json
• packages/linux-x64-musl/package.json
• packages/win32-arm64-msvc/package.json
• packages/win32-x64-msvc/package.json

Example package

Update "version" in examples/node/package.json.

Note: Do not update benchmarks/node/package.json -- it is a private package with its own independent version.

Documentation and READMEs

Search all documentation files for hardcoded SheetKit version references and update them to the new version using the full major.minor.patch format (e.g., 0.4.0).

Files that typically contain version references:

• README.md -- Rust installation example (sheetkit = "X.Y.Z")
• README.ko.md -- same as above
• docs/getting-started.md -- Rust dependency example
• docs/ko/getting-started.md -- same as above
• docs/guide/basic-operations.md -- Rust dependency example
• docs/ko/guide/basic-operations.md -- same as above
• docs/guide/index.md -- Rust dependency example
• docs/ko/guide/index.md -- same as above

To find all occurrences, run:

grep -rn 'sheetkit\s*=\s*"[0-9]' README.md README.ko.md docs/
grep -rn 'sheetkit.*version\s*=\s*"[0-9]' README.md README.ko.md docs/

Update every match to the new version. Do not change toolchain versions (Node.js, Rust) or other unrelated version numbers in documentation.

Step 2: Build and verify

Run these commands in order to rebuild everything with the new version:

pnpm install
pnpm -r build
cargo build --workspace

Then run lint/format checks:

pnpm check:fix
cargo fmt --check
cargo clippy --workspace

If pnpm check:fix modifies any files, those changes should be included in the release commit.

Finally, run the test suites:

cargo test --workspace
pnpm -r test

Step 3: Commit

Stage only the version-bumped and build-affected files. Do not use git add -A or git add ..

Files to stage:

git add Cargo.toml Cargo.lock \
  packages/sheetkit/Cargo.toml \
  packages/sheetkit/package.json \
  packages/darwin-arm64/package.json \
  packages/darwin-x64/package.json \
  packages/linux-arm64-gnu/package.json \
  packages/linux-arm64-musl/package.json \
  packages/linux-x64-gnu/package.json \
  packages/linux-x64-musl/package.json \
  packages/win32-arm64-msvc/package.json \
  packages/win32-x64-msvc/package.json \
  examples/node/package.json

Also stage any documentation files where versions were updated:

git add README.md README.ko.md \
  docs/getting-started.md \
  docs/ko/getting-started.md \
  docs/guide/basic-operations.md \
  docs/ko/guide/basic-operations.md \
  docs/guide/index.md \
  docs/ko/guide/index.md

Also stage any files modified by pnpm check:fix or cargo fmt.

Commit with the message:

git commit -m "release: vX.Y.Z"

Step 4: Tag

Create an annotated tag with the v prefix. Always use -m to provide a tag message (avoids opening an editor for GPG-signed tags):

git tag -a vX.Y.Z -m "vX.Y.Z"

Step 5: Push

Push the commit and tag together:

git push origin main vX.Y.Z

Step 6: Create GitHub draft release

Generate a changelog by analyzing the git log between the previous release tag and the new tag.

1. Find the previous release tag:

   git tag -l 'v*' --sort=-v:refname | head -2
   

   The second entry is the previous release.

2. Collect commits since the previous release:

   git log --oneline vPREVIOUS..vX.Y.Z
   

3. Categorize commits and write a changelog body in this format:

   ## What's Changed
   
   ### New Features
   -  Description of feature (PR #N)
   
   ### Performance
   -  Description of optimization (PR #N)
   
   ### Bug Fixes
   -  Description of fix (PR #N)
   
   ### Documentation
   -  Description of doc change (PR #N)
   
   ### Other
   -  Description of other change (PR #N)
   

   Omit any empty categories. Reference PR numbers where available. Write descriptions from the user's perspective, not internal details.

4. Create the draft release using gh:

   gh release create vX.Y.Z \
     --title "vX.Y.Z" \
     --draft \
     --notes "$(cat <<'EOF'
   <changelog body here>
   EOF
   )"
   

Version format reference

• Tags use the v prefix: v0.3.0, v1.0.0
• Cargo.toml versions omit the prefix: 0.3.0, 1.0.0
• package.json versions omit the prefix: 0.3.0, 1.0.0
• Commit message format: release: vX.Y.Z
• Tag message format: vX.Y.Z

Files that contain version numbers

A complete list for quick reference:

| File | Fields to update | |------|-----------------| | Cargo.toml | workspace.package.version, workspace.dependencies.sheetkit-xml.version, workspace.dependencies.sheetkit-core.version | | packages/sheetkit/Cargo.toml | version | | packages/sheetkit/package.json | version, 8x optionalDependencies | | packages/darwin-arm64/package.json | version | | packages/darwin-x64/package.json | version | | packages/linux-arm64-gnu/package.json | version | | packages/linux-arm64-musl/package.json | version | | packages/linux-x64-gnu/package.json | version | | packages/linux-x64-musl/package.json | version | | packages/win32-arm64-msvc/package.json | version | | packages/win32-x64-msvc/package.json | version | | examples/node/package.json | version | | README.md | Rust dependency example version | | README.ko.md | Rust dependency example version | | docs/getting-started.md | Rust dependency example version | | docs/ko/getting-started.md | Rust dependency example version | | docs/guide/basic-operations.md | Rust dependency example version | | docs/ko/guide/basic-operations.md | Rust dependency example version | | docs/guide/index.md | Rust dependency example version | | docs/ko/guide/index.md | Rust dependency example version |

Checklist summary

• [ ] On main branch, up to date
• [ ] All tests pass before starting
• [ ] Version bumped in Cargo.toml (3 fields)
• [ ] Version bumped in packages/sheetkit/Cargo.toml
• [ ] Version bumped in packages/sheetkit/package.json (version + 8 optionalDeps)
• [ ] Version bumped in 8 platform package.json files
• [ ] Version bumped in examples/node/package.json
• [ ] Version bumped in READMEs and docs
• [ ] pnpm install and pnpm -r build succeed
• [ ] cargo build --workspace succeeds
• [ ] pnpm check:fix and cargo fmt --check pass
• [ ] cargo test --workspace passes
• [ ] pnpm -r test passes
• [ ] Committed with message release: vX.Y.Z
• [ ] Tag vX.Y.Z created with -m "vX.Y.Z"
• [ ] Pushed commit and tag to origin
• [ ] GitHub draft release created with changelog