From 87a8d9c086d51c17cdfdd626d0e570dc858bfecc Mon Sep 17 00:00:00 2001 From: octalpixel Date: Thu, 25 Jun 2026 18:04:50 +0530 Subject: [PATCH] chore(release): adopt changesets with bun + workspace:^ inter-package deps MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaces hand-bumping versions + manual npm publish (the source of this session's release friction: core stuck at 2.1.0 while server ran to 2.4.0, a CHANGELOG number collision, the playground pinned to a stale ^1.3.0). Researched + verified the bun gotcha: `changeset publish` does NOT resolve bun's `workspace:` protocol (it uses npm), but `bun publish` DOES (`workspace:^` → `^` at pack time). So we version with Changesets and publish with `bun publish`. Verified: `bun pm pack` on @samesake/server emits `"@samesake/core": "^2.5.0"`. - Inter-package deps (server, cli) → `workspace:^`: dev always resolves to local; publish rewrites to a real range. Peer ranges left loose. - .changeset/config.json (access public, baseBranch main, private packages excluded from versioning). - root scripts: build, changeset, ci:version (`changeset version && bun update`), ci:publish (build → `bun publish` each packages/* → `changeset tag`). - .github/workflows/release.yml (changesets/action, bun) — needs an NPM_TOKEN secret to publish. - RELEASING.md documents the flow + the bun-specific reasoning. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01UeVCwYURGVrm2TFtQmWB3s --- .changeset/README.md | 8 +++++ .changeset/config.json | 12 +++++++ .changeset/workspace-protocol-deps.md | 9 ++++++ .github/workflows/release.yml | 37 +++++++++++++++++++++ RELEASING.md | 46 +++++++++++++++++++++++++++ package.json | 7 +++- packages/cli/package.json | 4 +-- packages/server/package.json | 2 +- 8 files changed, 121 insertions(+), 4 deletions(-) create mode 100644 .changeset/README.md create mode 100644 .changeset/config.json create mode 100644 .changeset/workspace-protocol-deps.md create mode 100644 .github/workflows/release.yml create mode 100644 RELEASING.md diff --git a/.changeset/README.md b/.changeset/README.md new file mode 100644 index 0000000..654c6d4 --- /dev/null +++ b/.changeset/README.md @@ -0,0 +1,8 @@ +# Changesets + +Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works +with multi-package repos, or single-package repos to help you version and publish your code. You can +find the full documentation for it [in our repository](https://github.com/changesets/changesets). + +We have a quick list of common questions to get you started engaging with this project in +[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md). diff --git a/.changeset/config.json b/.changeset/config.json new file mode 100644 index 0000000..a27f57b --- /dev/null +++ b/.changeset/config.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json", + "changelog": "@changesets/cli/changelog", + "commit": false, + "fixed": [], + "linked": [], + "access": "public", + "baseBranch": "main", + "updateInternalDependencies": "patch", + "ignore": [], + "privatePackages": { "version": false, "tag": false } +} diff --git a/.changeset/workspace-protocol-deps.md b/.changeset/workspace-protocol-deps.md new file mode 100644 index 0000000..19db2ad --- /dev/null +++ b/.changeset/workspace-protocol-deps.md @@ -0,0 +1,9 @@ +--- +"@samesake/server": patch +"@samesake/cli": patch +--- + +Use `workspace:^` for inter-package dependencies. In dev this always resolves to the local +workspace package; at publish `bun publish` rewrites it to a real `^` (verified via +`bun pm pack`). Replaces the previous loose `^2.0.0` ranges that could silently resolve to a stale +published version (the bug that left `apps/playground` pinned to `^1.3.0`). diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..56b35d8 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,37 @@ +name: release + +# Changesets + bun. On push to main: if changesets are pending, open a "version packages" PR +# (runs ci:version). When that PR merges, publish whatever is ahead of npm (runs ci:publish). +# NOTE: publishing uses `bun publish` (not `changeset publish`) because only bun resolves the +# `workspace:^` protocol → a real `^version` in the published package.json. + +on: + push: + branches: [main] + +concurrency: release-${{ github.ref }} + +permissions: + contents: write + pull-requests: write + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: oven-sh/setup-bun@v2 + with: + bun-version: latest + - name: Configure npm auth + run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc + - run: bun install + - name: Version or publish + uses: changesets/action@v1 + with: + version: bun run ci:version + publish: bun run ci:publish + commit: "chore: version packages" + title: "chore: version packages" + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..6f6e3f3 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,46 @@ +# Releasing + +Versioning + publishing is driven by [Changesets](https://github.com/changesets/changesets), +adapted for **bun**. The one bun-specific gotcha (researched + verified): + +> `changeset publish` does **not** resolve bun's `workspace:` protocol — it shells out to +> `npm publish`, and npm leaves `workspace:^` in the published `package.json` (a broken install). +> **`bun publish` does** resolve it: `workspace:^` → `^` at pack time. So we version with +> Changesets but publish with `bun publish`. + +Inter-package deps therefore use `workspace:^` (e.g. `@samesake/server` → `@samesake/core: "workspace:^"`). +In dev that always resolves to the local package (no version-range guessing — the bug that left +`apps/playground` pinned to a stale `^1.3.0`). At publish, `bun pm pack`/`bun publish` rewrite it to +the real `^`. Verified: `bun pm pack` on `@samesake/server` emits `"@samesake/core": "^2.5.0"`. + +## Day-to-day + +Add a changeset with every user-facing change: + +```bash +bun run changeset # pick packages + bump type, write the changelog line +git add .changeset && git commit +``` + +## Cutting a release + +Automated via `.github/workflows/release.yml` (needs an `NPM_TOKEN` repo secret): +on push to `main`, the changesets action opens a **"version packages"** PR; merging it publishes +everything ahead of npm. + +To release manually: + +```bash +bun run ci:version # changeset version && bun update → bumps + per-package CHANGELOGs + lockfile +git commit -am "chore: version packages" +bun run ci:publish # build, `bun publish` each packages/* (skips already-published), then tag +git push --follow-tags +``` + +`ci:publish` loops `packages/*` and runs `bun publish || true`, so already-published versions are +skipped and only the bumped ones go out. Private packages (`apps/*`, `examples/*`) are never published. + +## Note on CHANGELOG + +Changesets writes a **per-package** `CHANGELOG.md` going forward. The root `CHANGELOG.md` is the +historical record through 2.5.0 (the last hand-maintained release). diff --git a/package.json b/package.json index c23e307..e81710f 100644 --- a/package.json +++ b/package.json @@ -13,9 +13,14 @@ "examples:hello-spaces": "bun examples/hello-spaces/run.ts", "examples:quickstart": "bun examples/quickstart/run.ts", "typecheck": "tsc --noEmit", - "pack:assert": "bun scripts/pack-assert.ts" + "pack:assert": "bun scripts/pack-assert.ts", + "build": "for d in packages/sdk packages/server packages/cli packages/mcp; do (cd \"$d\" && bun run build) || exit 1; done", + "changeset": "changeset", + "ci:version": "changeset version && bun update", + "ci:publish": "bun run build && for dir in packages/*; do (cd \"$dir\" && bun publish || true); done && changeset tag" }, "devDependencies": { + "@changesets/cli": "^2.31.0", "@types/bun": "latest", "drizzle-kit": "^0.31.10", "tsup": "^8.5.1" diff --git a/packages/cli/package.json b/packages/cli/package.json index 67633a4..91a8dc5 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -30,8 +30,8 @@ "samesake" ], "dependencies": { - "@samesake/core": "^2.0.0", - "@samesake/server": "^2.0.0" + "@samesake/core": "workspace:^", + "@samesake/server": "workspace:^" }, "devDependencies": { "tsup": "^8.5.1" diff --git a/packages/server/package.json b/packages/server/package.json index 8aa869e..e8bb458 100644 --- a/packages/server/package.json +++ b/packages/server/package.json @@ -51,7 +51,7 @@ "zod": "^4.0.0" }, "dependencies": { - "@samesake/core": "^2.0.0" + "@samesake/core": "workspace:^" }, "devDependencies": { "@hono/zod-validator": "^0.8.0",