docs(release): explain the 2.0.0 alignment and the FFI publishing-repository change - #913
Merged
Conversation
…, and stop the CHANGELOG preamble shipping Three defects found auditing the Version Packages PR (#859), all in what consumers will read on npm. **Five packages ship a major with nothing to show for it.** `stash`, `@cipherstash/stack`, `stack-drizzle`, `stack-supabase` and `wizard` go 1.0.0 → 2.0.0 carrying only Minor and Patch entries — `wizard` carrying none at all, a heading followed by two blank lines. The one real breaking change is in `stack-prisma` (Prisma Next 0.17), and the other five inherit its number through the Changesets `fixed` group. Nothing in 485 lines of release notes said so, so a `stack-drizzle` user would have gone looking for a migration guide that does not exist. A changeset now says it in the changelog itself, where they will actually look, and explains why the packages are versioned together: `stash` embeds the versions it installs, so a package shipping alone would leave the CLI recommending versions that no longer match what is published. **The six platform packages had no entry at all.** 0.32.0 is their first release published from `cipherstash/stack` rather than `cipherstash/protectjs-ffi`, and the attested provenance repository changes with it — a verification policy that pins the source repository rejects 0.32.0 until updated. That was invisible to the person it affects, who reads the platform package they install rather than the wrapper. **The CHANGELOG preamble was publishing as release notes.** `changeset version` splices each release directly after the `# Changelog` line, so the hand-written preamble beneath it landed inside the newest section, under its heading: thirteen lines of 0.32.0 ending with "Write a changeset, not a section here" — an instruction to contributors, shipped to npm. It moves below the generated entries, where it explains the file's two halves and cannot be swept again, with a comment recording why nothing may sit above the first release heading. Verified by running `changeset version` and rolling it back: the seven FFI packages still land on 0.32.0 and the six Stack packages on 2.0.0 — these changesets add prose, not version bumps — `wizard`'s and each platform package's entries are no longer empty, and no preamble text remains inside 0.32.0.
🦋 Changeset detectedLatest commit: d200ae6 The changes in this PR will be included in the next version bump. This PR includes changesets to release 18 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
…se notes reach npm Review findings on the previous commit, all in text it would have published. **"No breaking changes in this package" was false for two of the five.** The same 2.0.0 ships `@cipherstash/stack`'s hex-only `clientKey` — a base64 value is now rejected at client construction — and `stash`'s removal of `stash eql validate --exclude-operator-family`, plus two checks that no longer exit 1. Both are recorded at patch and minor respectively, which is a deliberate maintainer call (#874: an undocumented decoder tolerance is not a contract break, and should not by itself take five packages to 2.0.0). That call is not reversed here — but a reader following "needs no code changes" into a failed client construction is not served by it either, so the note now names both, says where they are, and confines the drop-in claim to users of neither. **"cipherstash/protectjs-ffi, which is now archived" was false.** The repository is live; archiving is the last step of the cutover, after this release. Stated as future, matching the sibling changeset that already had it right. **The notes did not reach the packages they were written for.** `CHANGELOG.md` was absent from `files` in `stack-drizzle`, `stack-supabase`, `stack-prisma`, the protect-ffi wrapper and all six platform packages — so the provenance note aimed at "the package a checker actually installs" shipped nowhere near it, and "its own changelog carries the upgrade steps" pointed a Prisma user at a file absent from their install. Added to all ten. Verified by `npm pack --dry-run`: `stack-drizzle` now carries its 34.3kB CHANGELOG. The platform packages' copies are generated by `changeset version`, and `_build-ffi-artifacts.yml` packs from `changeset-release/main` after that runs, so the file exists at pack time. **`repository.directory` does not point at the crate.** It points at each platform's own stub under `packages/protect-ffi/platforms/`; only `repository.url` moved to `cipherstash/stack`. **The moved CHANGELOG section contradicted itself.** The heading excluded 0.31.0 while its first line included it, and its comment stated a rule stricter than the real invariant — the constraint is headingless prose, since a heading terminates the preceding section. Both corrected, and the comment's claim about npm, false when written, is true now that the file is in `files`. Versions are unchanged: seven FFI packages at minor, six Stack packages at major. `test:scripts` 416 passing; all ten manifests parse.
…rect two stale changelog identities **The references dangled in three of the five packages they render into.** The alignment note pointed readers at "Adopt protect-ffi 0.31.0 under Patch Changes" and "the `eql validate` entry under Minor Changes". Those sections exist in `@cipherstash/stack`'s and `stash`'s changelogs — not in `stack-drizzle`'s, `stack-supabase`'s or `wizard`'s, where the same entry is also rendered, and where `wizard@2.0.0` has no other sections at all. Each reference now names the package whose changelog holds it, so it resolves from wherever it is read. **`packages/stack-prisma/CHANGELOG.md` still identified itself as `@cipherstash/prisma-next`**, stale since the rename in #844. Harmless while the file stayed out of the tarball; adding it to `files` in the previous commit made it customer-visible, so the heading is corrected in the same release that starts shipping it. **`packages/cli/CHANGELOG.md` had the same defect and was already shipping it.** Its heading read `@cipherstash/cli`, a name that does not exist on npm — the package is `stash`, and this file has been in its `files` list all along. Not caused by this PR, but it is one line and the same class of error. All six published Stack packages now have a changelog heading matching their package name. Verified by running `changeset version` and rolling it back: no "under Patch Changes" / "under Minor Changes" reference survives anywhere, and `wizard@2.0.0` — which has no entries of its own — renders both references naming `@cipherstash/stack` and `stash`. Versions unchanged. `test:scripts` 416 passing.
coderdan
reviewed
Aug 19, 2026
Comment on lines
+9
to
+13
| **Why this package went to 2.0.0.** The major version number comes from | ||
| `@cipherstash/stack-prisma`, which moves to Prisma Next 0.17 — a breaking change | ||
| for its consumers, with the upgrade steps in its own Major Changes entry. These | ||
| six packages share one version line, so a major in any of them takes all six to | ||
| the same number: |
Contributor
There was a problem hiding this comment.
I still feel conflicted about this. Prisma Next went from 0.16 to 0.17 but we are going from 1.0.0 to 2.0.0. Worth mentioning that Prisma Next will eventually be released as Prisma 8.0.0.
Versions. What even are they.
coderdan
approved these changes
Aug 19, 2026
coderdan
left a comment
coderdan
left a comment
Contributor
There was a problem hiding this comment.
Approving because my comment is an opinion not a blocker. Interested in other view points.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three defects found auditing #859's release notes. All three are in what consumers read on npm, and all three are fixed by changing what #859 will regenerate — merge this before merging #859.
1. Five packages ship a major with nothing to show for it
stash,@cipherstash/stack,stack-drizzle,stack-supabaseandwizardgo 1.0.0 → 2.0.0 carrying only Minor and Patch entries.@cipherstash/wizard@2.0.0is a heading followed by two blank lines — on npm that reads as lost release notes, not "nothing changed".The one real breaking change is
@cipherstash/stack-prisma(Prisma Next 0.17). The other five inherit its number through the Changesetsfixedgroup, and nothing in 485 lines of release notes said so. Astack-drizzleuser would see 2.0.0, go looking for the migration guide, and find patch notes..changeset/stack-2-0-0-version-alignment.mdsays it in the changelog itself — where they will actually look, rather than in a PR description that is not published — and explains why the six are versioned together:stash initpins the versions it installs and the CLI embeds that map at build time, so a package shipping alone would leave the CLI recommending versions that no longer match what is published (#661,d8039141).2. The six platform packages had no entry at all
0.32.0 is the first release of these packages published from
cipherstash/stack. The attested provenance repository changes with it:A verification policy pinning the source repository rejects 0.32.0 until updated. The wrapper's patch note covers the repository repoint, but it sits 270 lines down and the six platform packages — the ones a provenance checker actually installs — had empty sections.
.changeset/ffi-platform-packages-publishing-repository.mdgives all six the note.3. The CHANGELOG preamble was publishing as release notes
changeset versionsplices each release directly after the# Changelogline, so the hand-written preamble beneath it landed inside the newest section, under its heading. In #859 that is body lines 296–309: thirteen lines rendered as part of 0.32.0, ending with— an instruction addressed to contributors, about to publish to npm. It would have recurred every release.
Moved below the generated entries, where it explains the file's two halves and cannot be swept again, with a comment recording why nothing may sit between
# Changelogand the first release heading.Verification
Ran
changeset versionfor real and rolled it back:@cipherstash/wizard@2.0.0and each platform package's0.32.0are no longer emptypnpm run test:scripts— 416 passingNot fixed here
e2e,basic-example,prisma-example,bench,test-kit) under a preamble saying packages "will be published to npm automatically". They will not — they areprivate. That ischangesets/actiontemplate behaviour, not something a changeset can correct.packages/stack/src/diagnostics.ts:26still says its changeset "is parked as.deferreduntil the publishing cutover". Stale since chore(release): retire the FFI publishing guard and activate its parked changesets #910.@cipherstash/nextjsis at 4.1.2 in this repo and 4.3.0 on npm — two minors published from somewhere else. Unrelated to this release, but worth knowing.