From ead0f11c8f9c6d3efd904b974e981b99d3761ee4 Mon Sep 17 00:00:00 2001 From: willbot Date: Wed, 15 Jul 2026 19:45:36 +0200 Subject: [PATCH 1/8] docs(drive): shape the prisma-8-rc1 release project (spec, plan, design notes) Records the settled Prisma 8 RC1 strategy as a Drive project: ship prisma@8.0.0-rc.1 from the merged prisma/prisma repo by July 31 2026. Spec carries the freeze-set requirements and DoD, plan carries the owner lanes and checkpoint milestones, design notes carry every settled decision with rationale and rejected alternatives. Signed-off-by: willbot Signed-off-by: Will Madden --- projects/prisma-8-rc1/design-notes.md | 76 +++++++++++++++++++ projects/prisma-8-rc1/plan.md | 95 ++++++++++++++++++++++++ projects/prisma-8-rc1/spec.md | 103 ++++++++++++++++++++++++++ 3 files changed, 274 insertions(+) create mode 100644 projects/prisma-8-rc1/design-notes.md create mode 100644 projects/prisma-8-rc1/plan.md create mode 100644 projects/prisma-8-rc1/spec.md diff --git a/projects/prisma-8-rc1/design-notes.md b/projects/prisma-8-rc1/design-notes.md new file mode 100644 index 0000000000..5bdf5004fd --- /dev/null +++ b/projects/prisma-8-rc1/design-notes.md @@ -0,0 +1,76 @@ +# Prisma 8 RC1 — Design Notes + +The settled decisions behind [spec.md](spec.md), each with its rationale. Alternatives considered are collected at the end. These were settled in operator discussion, July 15 2026. + +## The release is an RC, and that defines the cut line + +"GA by July 31" reframed as **Prisma 8.0.0-rc.1**. An RC freezes API surface; it does not promise completeness. That gives every work item a mechanical classification: it either affects frozen surface (must land before Jul 31) or it doesn't (may trail). The freeze set: package names, error codes, config keys, the `migrations/` directory layout, CLI bin names, version floors. The release bar is "everything we ship works, and we're confident" — not v7 parity. + +## Version number: 8 + +Skipping to 10 buys a vague "big jump" signal at the cost of permanent "what happened to 8 and 9" noise; the discontinuity story is already told by the architecture and the marketing. The RC publishes under a non-`latest` dist-tag so `npm install prisma` keeps resolving to v7 until 8.0.0 final — nobody gets v8 by accident, which defuses most same-package-name risk. + +## Repo merge: on a branch early, to main at the end + +The v8 branch lands in `prisma/prisma` immediately and runs full CI for weeks; merge mechanics (history graft, CI wiring, publish pipeline) are proven long before release week. The mass issue-close (everything except v7 bugs) happens **at merge time** with a pinned explanation issue — doing it early generates weeks of confused reactions with no announcement to point at. v7 history lives on a `v7` maintenance branch: bug fixes for **12 months, clock starting at 8.0.0 final** (not RC — an RC-dated clock silently shortens the promise if final slips, and generosity toward the v7 base is the right trade given low EA uptake). + +## Parallel install: three collision surfaces, three answers + +1. **npm names.** No collisions: Prisma Next has its own package set and no client in v7's sense, so `@prisma/client` stays v7-only. Library-level coexistence is the documented alias pattern (`"prisma-v7": "npm:prisma@^7"`). +2. **The CLI bin.** Both packages want a bin named `prisma`. Resolution: v8's `prisma` package ships **two bins — `prisma` and `prisma-next`** — and during coexistence v7 keeps winning `prisma`, so existing scripts and CI never break; users drive v8 explicitly via `prisma-next` (which EA users already type). At cutover, v7 is removed and `prisma` points at v8. `prisma8` was considered and dropped: `prisma-next` already exists, is already in muscle memory, and avoids migrating users' habits twice. Long-term CLI home (`@prisma/cli`, prisma/prisma-cli) is compatible with this and out of scope. +3. **Migration ownership.** Two migration systems must never both mutate one schema. **v7 owns migrations until a single final cutover.** v8 adopts the database read-only via the shipped, e2e-tested brownfield path (ADR 122): `contract infer` → `db sign` (which verifies the live schema satisfies the contract before writing anything, then records only a marker in the reserved `prisma_contract` schema — it never touches `_prisma_migrations`). After each v7 migration during coexistence: re-infer, review the diff, re-sign; `db verify --schema-only` in CI. At cutover: final sign against the last v7-migrated state, then normal v8 migration flow. + +**Known wrinkle:** v7 puts `_prisma_migrations` in `public`, so it is an "unclaimed element" to v8 — tolerated by default `db verify`, but a failure under `--strict` and flagged by `db init`. The upgrade guide blesses **lenient mode until cutover** (one paragraph) rather than building an ignore/allowlist mechanism (a feature nobody needs after the transition). + +**Known gaps on this path:** the Dub.co side-by-side evaluation (WS1 M4) never ran — the fixture (plan S1) is the first real test of the coexistence claim. `migration plan --advance` (TML-2560) is documented but unimplemented; it sits on the *cutover* path, not the parallel-run path, so it is a named public gap for final, not an RC blocker. Brownfield step-count ergonomics are tracked as TML-2561. + +## Packaging: rename only the visible set; consolidation is already designed + +The repo publishes 65 lockstep-versioned packages, but npm existence isn't the ratchet — **blessing is**. ADR 211 already defines the end state: the unscoped bin-only shim plus the three target facades are the entire user-facing surface; everything else is implementation detail, and Flavor 2 (TML-2265) later bundles internals into the shim so they stop being published — non-breaking, hence deferred past RC. So the July move is small: the shim becomes `prisma@8.0.0-rc.1`, and the facades become `@prisma/postgres` / `@prisma/sqlite` / `@prisma/mongo` **at RC** (RC is the freeze moment — renaming between RC and final would break the one promise an RC makes). The rename set is collision-audited against classic-owned `@prisma/*` names (`client`, `config`, `engines`, `adapter-*`, …) because parallel-installed users resolve both scopes simultaneously. All other `@prisma-next/*` packages stay published and untouched. + +The repo rename (`prisma/prisma` → `prisma/prisma-orm`) is parked: GitHub redirects make it cheap whenever it happens, and it doesn't need to ride along with the merge. + +## Version floors: already ratified, one under revisit + +ADR 222 ratified Node ≥24, TS ≥5.9 (optional peer), ESM-only, Postgres 17, MongoDB 8.0 — so "clear Node + TS version requirements" is announcement copy, not engineering. Node ≥24 and ESM-only are themselves headline breaking changes and lead the upgrade guide. The **Postgres 17 floor was an EA-era convenience** and is being revisited (decision due Jul 22): the migrating-from-v7 audience skews to older Postgres, and a floor that excludes them contradicts the incremental-migration promise. Each supported floor version is a permanent CI matrix row — that cost is the decision. + +## Error codes: one scheme, decided before the freeze + +The current state is four parallel error models with two incompatible code formats (~46 `PN-DOMAIN-NNNN` in the CLI layer, ~89 dotted `NAMESPACE.SUBCODE` in the runtime and migration-tools layers), ~16 codeless bespoke classes, and no central registry — ADR 027's factory/registry/redaction spec is unimplemented. The consistency pass is mechanical and parallelizable *once a scheme is ratified*; the ratification (due Jul 18) is the bottleneck. Recommendation on the table: **dotted wins** (twice the usage, self-describing), with a published crosswalk for the PN codes per ADR 027's own stability policy. Codes freeze at RC; message wording and golden-test scaffolding may trail. There is deliberately **no classic P-code compatibility** — the clean break already shipped; the upgrade guide gets a P-code → new-code mapping table for the runbook-migration crowd instead. + +## Migration snapshot centralization: pre-freeze by necessity + +Every migration directory currently carries redundant contract copies; a chain of M migrations stores ~2M contracts where M+1 distinct ones exist. The fix is content-addressed storage — `migrations/snapshots/.json` — mirroring the `prisma_contract.contract` table the database side already has. Migration dirs need no link files: `migration.json` already carries the from/to hashes, so the contract-reference resolver learns the snapshot store and the change concentrates in resolver + emitter (+ example regeneration). This is **safe** because ADR 199 excludes snapshots from migration identity (hash covers manifest + ops only) — nothing invalidates. It is **urgent** because the `migrations/` layout becomes frozen public surface at RC. Compression: writer emits plain JSON (git packs already delta-compress; gzipped blobs cost PR reviewability and greppability), but the reader accepts `.json.gz` from day one so compression remains a future non-breaking writer-side option. + +## Testing: mine P7, don't convert it + +The P7 functional suite is thousands of tests against a different API; wholesale conversion is months. The valuable artifact is the **database and relational-algebra edge cases encoded in it**. Two moves: (1) extract those scenarios, filtered by the supported-surface matrix, into the existing `test/integration/` + `test/e2e/` per-target structure — the matrix and the converted tests become the same artifact, making "everything we ship works" checkable; (2) differential testing through the side-by-side fixture where v7-as-oracle beats hand-porting assertions. With thin EA adoption, this suite does the confidence work production feedback normally would. + +## Benchmarks: public Bencher, measurements only + +TS performance is measured **before** the type freeze (deep conditional types are exactly the pattern that blows up check time at schema scale — if the numbers are bad, the runway to fix types exists only pre-freeze). Public surface: a **Bencher project (public, free for OSS)** carrying per-commit series — `tsc --extendedDiagnostics` check time, type instantiations, memory — split by schema size (10/100/500 models) and TS version (5.9, 7). **Measurements only, no v7 or competitor comparison**: fair comparison is hard, and a comparative claim makes the benchmark the story. PR regression checks fail on **instantiation counts** (deterministic) rather than wall time (CI-runner jitter). Consequence, accepted: the announcement can't say "dramatically faster types" with a public receipt — wording is calibrated against one internal v7 comparison run, or softened to what the dashboard shows. + +## Dashboards + +- **Pre-RC, org-internal:** the Linear project *is* the dashboard — milestones carry the checkpoints, status updates land at each one, and tickets are created just-in-time (an exhaustive up-front backlog was explicitly rejected as waste under a fast-changing plan). Any separate internal page is a second copy of Linear that goes stale. +- **Post-RC, public:** road-to-final dashboard derived from maintained-under-pressure sources only — the supported-surface matrix as checked-in data, cell status keyed to named CI suites, gaps as GitHub issues on an `8.0.0` milestone. Promises limited to: API stability with named experimental carve-outs, the 12-month v7 window, **promotion criteria instead of a date** (every cell green or explicitly not-in-8.0; N weeks without a new release-blocker; the migration recipe passing its fixture), the explicit not-in-8.0 list, and a biweekly status cadence. Rule: nothing goes public that we aren't willing to be held to in a GitHub thread six weeks later — per-feature dates fail that test. + +## Staffing + +Will (lead: merge, npm ops, decisions, announcement, and the agent-executed engineering under his review), Serhii (coexistence fixture, then test mining), Alexey (polymorphism, untouched, through the go/no-go). Agent-executed work lands as bot PRs and costs Will review time, not implementation time — the split that keeps the lead off the critical path for everything except the things only the lead can do. + +## Alternatives considered + +- **Version 10** — rejected: permanent numbering noise for a signal the marketing already carries. +- **Reusing classic P-codes (P1001-style)** — rejected: zero compatibility exists in the codebase by design; retrofitting would break EA users to please v7 muscle memory. A mapping table in the upgrade guide serves the runbook crowd instead. +- **`prisma8` as the coexistence bin** — rejected in favor of keeping `prisma-next`: it already exists and EA users already use it; no second habit migration. +- **v8 claiming the `prisma` bin during coexistence** — rejected: breaks every existing v7 script and CI job on install. +- **Both migration systems owning DDL** — rejected: requires reconciliation machinery that doesn't exist; single-owner-until-cutover is the shipped, tested model. +- **An ignore/allowlist mechanism for v7's `_prisma_migrations` under `db verify --strict`** — rejected for now: lenient-mode guidance is one paragraph; the allowlist is a feature with a lifespan of one transition. +- **Renaming all 65 packages to `@prisma/*` at RC** — rejected: blesses ~65 names as frozen public API; only the visible set (shim + facades) is user-facing per ADR 211. +- **ADR 211 Flavor 2 bundling before RC** — rejected: non-breaking later, unnecessary risk in a 13-day window. +- **Wholesale P7 test-suite conversion** — rejected: months of work porting assertions written against a different API; mining + differential testing capture the value. +- **Comparative public benchmarks (v7, competitors)** — rejected: fair methodology is its own project, and the comparison becomes the story. +- **Hand-curated public roadmap page** — rejected: goes stale in weeks; every stale cell reads as a broken promise. Derive from maintained sources or don't publish. +- **Exhaustive up-front Linear backlog** — rejected by the operator: the plan changes too fast; milestones + just-in-time tickets instead. +- **Gzipping snapshots at write time** — deferred: dedup is the big win; git already compresses; reviewability wins. Reader-side `.gz` tolerance ships so the option stays open without a second layout break. diff --git a/projects/prisma-8-rc1/plan.md b/projects/prisma-8-rc1/plan.md new file mode 100644 index 0000000000..4b16ac45c5 --- /dev/null +++ b/projects/prisma-8-rc1/plan.md @@ -0,0 +1,95 @@ +# Prisma 8 RC1 — Project Plan + +## Summary + +Thirteen working days (Jul 15 → Jul 31 2026), three people plus agent capacity, four checkpoint milestones. Slices are grouped by owner lane; sequencing constraints are noted where they exist — everything else runs in parallel. Tickets are created just-in-time when a slice starts, never up-front. + +**Spec:** [spec.md](spec.md) · **Design notes:** [design-notes.md](design-notes.md) · **Tracking:** [Linear — Prisma 8 RC1](https://linear.app/prisma-company/project/prisma-8-rc1-7592265f700c) + +## Checkpoints (Linear milestones) + +| Date | Milestone | What must be true | +| --- | --- | --- | +| Fri Jul 18 | Error-code scheme ratified | Will decides dotted vs PN-numeric; sweep unblocked | +| Tue Jul 22 | Postgres floor decided | Keep 17 or lower it; supported-surface matrix unblocked | +| Thu Jul 24 | Go/no-go | Polymorphism in/out called; matrix frozen; side-by-side fixture green (or the coexistence claim is softened) | +| Thu Jul 31 | RC1 published & announced | Release-week mechanicals complete; announcement live | + +## Lane: Will — merge, ops, decisions + +### Slice W1: v8 branch + CI in prisma/prisma — **critical path, start immediately** + +Merge prisma-next content onto a `v8` branch in `prisma/prisma`; get the full CI suite green there and keep it green for the rest of the project. Includes deciding the history graft (v7 history under main vs parallel histories) via a dry run in a fork first. Merge to `main` happens in release week (W4), not before. + +### Slice W2: npm ops on the `prisma` package — **critical path, external dependency, chase first** + +Obtain publish rights and OIDC trusted-publisher configuration on the `prisma` npm package; confirm v7's release automation tolerates a second publisher under a different dist-tag. Also: collision audit of the visible rename set (`@prisma/postgres`, `@prisma/sqlite`, `@prisma/mongo`) against classic-owned `@prisma/*` names. + +### Slice W3: decisions + +Error-code scheme (Jul 18), Postgres floor (Jul 22), polymorphism go/no-go (Jul 24). Each unblocks a slice below. + +### Slice W4: release week mechanicals (Jul 28–31) + +Lockstep version to `8.0.0-rc.1` (`set-version`); visible-set rename (shim → `prisma`, facades → `@prisma/*`); `v7` maintenance branch cut with CI; merge v8 branch → main; issue-close sweep with pinned explanation issue and saved reply; publish under non-`latest` dist-tag; announcement live. + +### Slice W5: announcement + upgrade guide + +Leads with Node ≥24 + ESM-only as headline breaking changes; parallel-install recipe (mirroring the fixture); 12-months-from-final v7 statement; supported-surface matrix; explicit not-in-8.0 list; links to Bencher. + +## Lane: Will (agent-executed) — mechanical engineering, lands as bot PRs + +### Slice A1: TS performance benchmark harness — **first dispatch, before the type freeze** + +Bench package generating synthetic schemas at 10/100/500 models; runs `tsc --extendedDiagnostics` across v8 under TS 5.9 and TS 7; emits Bencher BMF JSON per CI run to a **public Bencher project**. PR regression check fails on type-instantiation counts (deterministic); wall time and memory tracked as informational trend. One internal v7 comparison run sanity-checks the announcement wording — never published. + +### Slice A2: migration contract-snapshot centralization — **pre-freeze (migrations/ layout freezes at RC)** + +Centralize per-migration contract copies into content-addressed `migrations/snapshots/.json`. Migration dirs reference contracts via the from/to hashes already in `migration.json`; the contract-reference resolver learns the snapshot store; emitter updated; example migrations regenerated. Safe because ADR 199 excludes snapshots from migration identity. Writer emits plain JSON; reader accepts `.json.gz` from day one (compression stays a future non-breaking option). + +### Slice A3: error-code consistency sweep — **blocked on W3 scheme decision (Jul 18)** + +Fold the four error models into the ratified scheme: fold in the ~16 codeless classes (SQL driver errors, bespoke tail, the duplicated `ContractValidationError`), normalize the losing format, build the central factory/registry ADR 027 assumes, publish the crosswalk. Codes freeze at RC; conformance/golden tests may trail. + +### Slice A4: `extensionPacks` → `extensions` rename (TML-2462) — **pre-freeze** + +Breaking config-key rename; must precede the API freeze. Record upgrade instructions per the breaking-change workflow. + +### Slice A5: Pool error-listener fix (TML-2655) + +Idle-reconnect errors crash the host process; production-readiness fix, not cleanup. + +### Slice A6: supported-surface matrix as structured data — **blocked on W3 floor decision (Jul 22)** + +Feature area × database target × status (`stable` / `experimental` / `not-in-8.0`), as checked-in structured data. Every `stable` cell names the test suite that proves it. Frozen at the Jul 24 checkpoint; seeds the public road-to-final dashboard post-RC and filters the P7 test mining (S2). + +## Lane: Serhii — coexistence proof + correctness + +### Slice S1: side-by-side fixture — **top risk, start immediately, zero dependencies** + +One repo, both versions installed (npm alias for v7), one Postgres database, v7 owning DDL. Exercises: initial adoption (`contract infer` → `db sign`), the standing loop after a v7 migration (re-infer → re-sign → `db verify --schema-only`), and dual-client queries against the same data. The Dub.co side-by-side evaluation (WS1 M4) never ran, so this fixture is the first-ever test of the RC's central claim. Must be green by Jul 24. + +### Slice S2: P7 test mining — **after S1, filtered by A6** + +Mine (don't convert) the P7 functional suite: extract the database and relational-algebra edge cases it encodes, scoped to what the matrix claims is stable, into `test/integration/` + `test/e2e/` following the existing per-target patterns. The fixture from S1 doubles as the differential harness where v7-as-oracle comparison is cheaper than porting assertions. + +## Lane: Alexey — polymorphism + +### Slice X1: MTI/variant-relation stabilization + +The ~10 active correctness bugs in SQL ORM polymorphism (variant relations, includes, update/delete predicates, namespace-flat variant resolution). The bug-discovery curve — not a completion promise — decides the Jul 24 call: flattened → in scope at RC; still producing → ships marked experimental and the stream continues post-RC. + +## Sequencing constraints (everything else is parallel) + +- W2 (npm rights) blocks nothing until release week, but its *external* nature means it starts first. +- W3 decisions block A3 (scheme) and A6 (floor); A6 blocks the S2 filter and the matrix freeze at the checkpoint. +- S1 must be green by Jul 24 or the coexistence claim in W5 is softened. +- A1, A2, A4, A5, S1, X1 have no upstream dependencies — all start immediately. +- W4 is strictly last and consumes everything. + +## Close-out (required) + +- [ ] Verify all acceptance criteria in [spec.md](spec.md) +- [ ] Migrate long-lived docs into `docs/` (upgrade guide, coexistence workflow, error-code scheme ADR + crosswalk, snapshot-layout ADR, supported-surface matrix home) +- [ ] Strip repo-wide references to `projects/prisma-8-rc1/**` +- [ ] Final retro; delete `projects/prisma-8-rc1/` diff --git a/projects/prisma-8-rc1/spec.md b/projects/prisma-8-rc1/spec.md new file mode 100644 index 0000000000..c45cb014e8 --- /dev/null +++ b/projects/prisma-8-rc1/spec.md @@ -0,0 +1,103 @@ +# Prisma 8 RC1 — Project Spec + +# Summary + +Ship Prisma Next as **`prisma@8.0.0-rc.1`, published from the merged `prisma/prisma` repository, by July 31 2026**, with the announcement live the same day. Users arrive at the same GitHub repository and install the same npm package they always have — and what they get is Prisma Next. + +# Purpose + +End the period where Prisma's future ORM lives in a separate repo under a separate name. One repository, one package name, one upgrade story — so that every user who looks for Prisma finds Prisma 8, and every v7 user has a concrete, tested path to run both versions side by side and migrate incrementally. + +The RC redefines the release bar: **not parity with Prisma 7, but confidence** — everything the RC ships works, the API surface it exposes is frozen, and everything it doesn't ship is named explicitly. + +# At a glance + +A v7 user's first contact with the RC, end to end: + +```jsonc +// package.json — both versions installed in one project +{ + "dependencies": { + "prisma-v7": "npm:prisma@^7", // existing app code keeps working + "prisma": "npm:prisma@next" // resolves to 8.0.0-rc.1 + } +} +``` + +```bash +# v7 keeps owning the database schema and migrations +npx -p prisma-v7 prisma migrate deploy + +# v8 adopts the same database read-only: infer a contract, verify, sign +prisma-next contract infer +prisma-next db sign # verifies the live schema satisfies the contract, then records a marker +prisma-next db verify --schema-only # CI check: schema still matches +``` + +New queries are written against the v8 client; old code paths stay on v7. At the end of the migration, ownership flips once: the final `db sign` against the last v7-migrated state, and v7 is removed. `npm install prisma` continues to resolve to v7 until `8.0.0` final ships — nobody gets v8 by accident. + +# Non-goals + +- **Prisma 7 feature parity.** The RC ships what works. Missing capabilities are named in the supported-surface matrix, not implied. +- **Guaranteed-stable polymorphism/MTI at RC.** In scope until the July 24 go/no-go; if the bug curve hasn't flattened, it ships marked experimental. +- **Renaming `prisma/prisma` → `prisma/prisma-orm`.** Parked. GitHub redirects make it cheap to do later; it does not need to ride along with the merge. +- **Migrating the internal toolchain to TypeScript 7.** Consumer-side TS 7 validation is in scope (types must work under the native compiler); switching our own build to it is not. +- **Comparative benchmarks.** The public benchmark surface is measurements-only (our own numbers over time). No v7 or competitor comparison — fair comparison is genuinely hard and the claim would become the story. +- **ADR 211 Flavor 2 bundling before RC.** Consolidating the ~60 internal `@prisma-next/*` packages into the shim is designed and non-breaking, and therefore deliberately deferred to after RC. +- **The public road-to-final dashboard.** Goes live *with* the RC announcement, not before. Pre-RC tracking is org-internal (the Linear project). +- **An exhaustive up-front ticket backlog.** Tickets are created just-in-time as work starts; the Linear project's milestones and status updates are the tracking surface. + +# Place in the larger world + +- **prisma/prisma** currently holds Prisma 7. This project merges prisma-next's content in **on a `v8` branch early** (CI running there for weeks) and merges to `main` in the final week. v7 history moves to a `v7` maintenance branch (bug fixes for 12 months from 8.0.0 final). At merge time, open v7 issues and PRs are closed except v7 bugs, with a pinned explanation issue. +- **The `prisma` npm package** is currently v7's. The RC publishes under a non-`latest` dist-tag; `latest` stays v7 until 8.0.0 final. Publishing requires npm rights + trusted-publisher (OIDC) configuration on that package — an external dependency chased first. +- **prisma/prisma-cli (`@prisma/cli`)** is the long-term CLI home; out of scope here but the bin strategy must not conflict with it. +- **EA shipped June 1** with good sentiment but little uptake — which means production feedback is thin, and the mined-from-P7 test suite plus the side-by-side fixture do the confidence work that adoption otherwise would. + +# Cross-cutting requirements + +1. **Parallel install must actually work, and be proven by a fixture.** One project, both versions installed, one Postgres database, v7 owning DDL. The npm alias covers library resolution; the bin conflict is resolved by v8 shipping both `prisma` and `prisma-next` bins with v7 winning `prisma` during coexistence; migration ownership stays with v7 until a single final cutover (adoption via `contract infer` → `db sign`, per ADR 122). The e2e fixture is simultaneously the coexistence proof, the differential-testing harness, and the executable form of the upgrade guide. +2. **Everything that freezes at RC must land before RC.** The freeze set: public package names, error codes, config keys (`extensionPacks` → `extensions`), the `migrations/` directory layout (snapshot centralization), CLI bin names, and the Node/TS/database version floors. Anything not in the freeze set may trail. +3. **Claims in the announcement must have receipts.** "Works" → the supported-surface matrix backed by named green test suites. "TS performance" → the public Bencher project. "Run both in parallel" → the fixture. No unverifiable claims. +4. **The org can see the state at any time.** The Linear project *Prisma 8 RC1* (lead: Will, milestones Jul 18 / Jul 22 / Jul 24 / Jul 31) is the internal dashboard; status updates at each milestone. + +# Transitional-shape constraints + +- The v8 branch lives in `prisma/prisma` with green CI for as long as possible before the final merge; merge mechanics are never last-week discoveries. +- The RC is never reachable via `npm install prisma` (non-`latest` dist-tag) until 8.0.0 final. +- Only the visible package set is renamed at RC (`prisma-next` shim → `prisma`; `@prisma-next/{postgres,sqlite,mongo}` facades → `@prisma/*`, collision-audited against classic's `@prisma/*` names). All other `@prisma-next/*` packages remain published and untouched until Flavor 2. +- During the coexistence period, `db verify` runs lenient (v7's `_prisma_migrations` table in `public` is an unclaimed element that fails `--strict`); the upgrade guide blesses lenient mode until cutover. + +# Project DoD + +- [ ] `prisma@8.0.0-rc.1` is published from the merged `prisma/prisma` repository under a non-`latest` dist-tag; `npm install prisma` still resolves to v7. +- [ ] The announcement is live, and every claim in it maps to a receipt (matrix, Bencher, fixture). +- [ ] The parallel-install recipe in the upgrade guide is backed by a green e2e fixture (both versions, one database, v7 owns DDL, adoption loop exercised after a v7 migration). +- [ ] The `v7` maintenance branch exists in `prisma/prisma` with working CI, and the 12-months-from-final support statement is published. +- [ ] User-facing error codes follow one consistent scheme, with a crosswalk for renamed codes; codes are frozen. +- [ ] `extensionPacks` → `extensions` rename (TML-2462) and the Pool error-listener fix (TML-2655) are merged. +- [ ] Migration contract snapshots are centralized under `migrations/snapshots/` (content-addressed); the reader accepts `.json.gz`. +- [ ] The supported-surface matrix (feature × target × stable/experimental/not-in-8.0) is published, with every "stable" cell backed by a named green suite. +- [ ] TS performance measurements (check time, type instantiations, memory; 10/100/500-model schemas; TS 5.9 and TS 7) are live on a public Bencher project, with instantiation-count regression checks on PRs. +- [ ] Open v7 issues/PRs are triaged per the merge policy (close all except v7 bugs, pinned explanation issue posted). + +# Open questions + +- **Error-code scheme** (due Jul 18, Will): dotted `NAMESPACE.SUBCODE` vs `PN-DOMAIN-NNNN`. Recommendation on the table: dotted wins; crosswalk the ~46 PN codes. +- **Postgres version floor** (due Jul 22, Will): keep 17 (EA-era convenience) or lower it for the migration audience. Every floor version is a CI matrix row forever. Blocks the supported-surface matrix. +- **Polymorphism/MTI in or out** (Jul 24 go/no-go): decided by Alexey's bug curve. +- **npm publish rights on `prisma`**: who grants them, and does v7's release automation assume exclusive ownership of the package? + +# References + +- Linear project: [Prisma 8 RC1](https://linear.app/prisma-company/project/prisma-8-rc1-7592265f700c) +- Design rationale and alternatives: [design-notes.md](design-notes.md) +- Plan: [plan.md](plan.md) +- ADR 021 — Contract Marker Storage & verification modes +- ADR 122 — Database Initialization & Adoption (the brownfield `infer → sign` path) +- ADR 123 — Drift Detection, Recovery & Reconciliation +- ADR 199 — Storage-only migration identity (why snapshot centralization is safe) +- ADR 211 — prisma-next bin-only distribution (the packaging end-state and Flavor 2) +- ADR 222 — Version support policy (Node ≥24, TS ≥5.9, ESM-only) +- ADR 027 / ADR 068 — Error envelope stable codes / error mapping (the error-consistency baseline) +- `docs/oss/versioning.md` — lockstep versioning, dist-tags, publish pipeline From 74fe07801350e8445524b6bf41d1ee2cf09a7729 Mon Sep 17 00:00:00 2001 From: willbot Date: Wed, 15 Jul 2026 19:49:07 +0200 Subject: [PATCH 2/8] docs(drive): derive the supported-surface matrix from two crossed sources; start it now Rows come from (1) the v8 surface enumerated from the codebase and (2) Prisma 7 capability taxonomy as the completeness checklist, so missing capabilities are named rather than silently absent. Phase 1 (enumeration + no-proving-suite list) has no dependencies and starts immediately; only the Jul 24 status freeze waits on the floor and polymorphism decisions. Signed-off-by: willbot Signed-off-by: Will Madden --- projects/prisma-8-rc1/plan.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/projects/prisma-8-rc1/plan.md b/projects/prisma-8-rc1/plan.md index 4b16ac45c5..f1f5ef8a89 100644 --- a/projects/prisma-8-rc1/plan.md +++ b/projects/prisma-8-rc1/plan.md @@ -59,9 +59,20 @@ Breaking config-key rename; must precede the API freeze. Record upgrade instruct Idle-reconnect errors crash the host process; production-readiness fix, not cleanup. -### Slice A6: supported-surface matrix as structured data — **blocked on W3 floor decision (Jul 22)** +### Slice A6: supported-surface matrix as structured data — **start now; only the freeze waits on decisions** -Feature area × database target × status (`stable` / `experimental` / `not-in-8.0`), as checked-in structured data. Every `stable` cell names the test suite that proves it. Frozen at the Jul 24 checkpoint; seeds the public road-to-final dashboard post-RC and filters the P7 test mining (S2). +Feature area × database target × status (`stable` / `experimental` / `not-in-8.0`), as checked-in structured data. Every `stable` cell names the test suite that proves it; every `not-in-8.0` cell is a deliberate statement, not an omission. + +**Where the rows come from — two sources, crossed:** + +1. *What v8 ships*, enumerated from the codebase: facade subpath exports (`@prisma-next/{postgres,sqlite,mongo}`), the CLI command tree, the PSL feature set (attributes, types, namespaces), the ORM/query-builder operation surface, the migration operation catalog, and the extensions. If it isn't reachable through the blessed surface, it isn't a row. +2. *What v7 users expect*: Prisma 7's capability taxonomy (docs navigation + the functional test suite's directory structure, which is a de-facto feature census). This is the completeness checklist that makes "missing capabilities are named" true — absence can only be named against an enumeration of what users look for. + +**Phase 1 (now, no dependencies):** enumerate rows, draft cell statuses, and list every stable-claimed cell with no proving suite — that list is S2's mining work-list. + +**Phase 2 (freeze at Jul 24):** stamp final statuses once the Postgres floor (Jul 22) and the polymorphism call (Jul 24) land. + +Feeds the S2 filter, the announcement's supported-surface section, and the post-RC public dashboard. ## Lane: Serhii — coexistence proof + correctness @@ -82,9 +93,9 @@ The ~10 active correctness bugs in SQL ORM polymorphism (variant relations, incl ## Sequencing constraints (everything else is parallel) - W2 (npm rights) blocks nothing until release week, but its *external* nature means it starts first. -- W3 decisions block A3 (scheme) and A6 (floor); A6 blocks the S2 filter and the matrix freeze at the checkpoint. -- S1 must be green by Jul 24 or the coexistence claim in W5 is softened. -- A1, A2, A4, A5, S1, X1 have no upstream dependencies — all start immediately. +- W3 decisions block A3 (scheme) and A6 *phase 2 only* (floor + polymorphism call); A6 phase 1 blocks nothing and starts now. +- A6 phase 1's no-proving-suite list is S2's work-list; S1 must be green by Jul 24 or the coexistence claim in W5 is softened. +- A1, A2, A4, A5, A6 phase 1, S1, X1 have no upstream dependencies — all start immediately. - W4 is strictly last and consumes everything. ## Close-out (required) From 7320c4a5270d3829b99c43e4e33731ed35fd3066 Mon Sep 17 00:00:00 2001 From: willbot Date: Wed, 15 Jul 2026 19:49:54 +0200 Subject: [PATCH 3/8] docs(drive): the rendered supported-surface matrix is the public dashboard No separate progress board: cells flipping from cross to tick as proving suites go green is the distance-to-done reading. Signed-off-by: willbot Signed-off-by: Will Madden --- projects/prisma-8-rc1/design-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/prisma-8-rc1/design-notes.md b/projects/prisma-8-rc1/design-notes.md index 5bdf5004fd..4d36640d07 100644 --- a/projects/prisma-8-rc1/design-notes.md +++ b/projects/prisma-8-rc1/design-notes.md @@ -53,7 +53,7 @@ TS performance is measured **before** the type freeze (deep conditional types ar ## Dashboards - **Pre-RC, org-internal:** the Linear project *is* the dashboard — milestones carry the checkpoints, status updates land at each one, and tickets are created just-in-time (an exhaustive up-front backlog was explicitly rejected as waste under a fast-changing plan). Any separate internal page is a second copy of Linear that goes stale. -- **Post-RC, public:** road-to-final dashboard derived from maintained-under-pressure sources only — the supported-surface matrix as checked-in data, cell status keyed to named CI suites, gaps as GitHub issues on an `8.0.0` milestone. Promises limited to: API stability with named experimental carve-outs, the 12-month v7 window, **promotion criteria instead of a date** (every cell green or explicitly not-in-8.0; N weeks without a new release-blocker; the migration recipe passing its fixture), the explicit not-in-8.0 list, and a biweekly status cadence. Rule: nothing goes public that we aren't willing to be held to in a GitHub thread six weeks later — per-feature dates fail that test. +- **Post-RC, public:** the rendered supported-surface matrix **is** the dashboard — a grid of ticks and crosses regenerated by CI from the checked-in data. There is no separate progress board: cells flipping from cross to tick as proving suites go green *is* the distance-to-done reading. Ticks link to the suite that proves them; deliberate crosses are the not-in-8.0 list and link to gap issues on an `8.0.0` milestone. Promises limited to: API stability with named experimental carve-outs, the 12-month v7 window, **promotion criteria instead of a date** (every cell green or explicitly not-in-8.0; N weeks without a new release-blocker; the migration recipe passing its fixture), the explicit not-in-8.0 list, and a biweekly status cadence. Rule: nothing goes public that we aren't willing to be held to in a GitHub thread six weeks later — per-feature dates fail that test. ## Staffing From 7fc6df55c51d98133fca89afb69547e0bf5fd68d Mon Sep 17 00:00:00 2001 From: willbot Date: Thu, 16 Jul 2026 09:56:55 +0200 Subject: [PATCH 4/8] docs(drive): restructure prisma-8-rc1 into shareable topic docs Replaces the owner-lane plan with a set of plain-English documents that go from high-level goals to concrete steps, independent of who does what: release definition, correctness scoreboard, feature surface, repo migration, parallel install, and a dated step plan. Ownership lives in Linear, not in these docs. Signed-off-by: willbot Signed-off-by: Will Madden --- projects/prisma-8-rc1/README.md | 16 +++ projects/prisma-8-rc1/feature-surface.md | 35 ++++++ projects/prisma-8-rc1/parallel-install.md | 64 ++++++++++ projects/prisma-8-rc1/plan.md | 131 ++++++++------------ projects/prisma-8-rc1/release-definition.md | 40 ++++++ projects/prisma-8-rc1/repo-migration.md | 47 +++++++ projects/prisma-8-rc1/scoreboard.md | 52 ++++++++ 7 files changed, 308 insertions(+), 77 deletions(-) create mode 100644 projects/prisma-8-rc1/README.md create mode 100644 projects/prisma-8-rc1/feature-surface.md create mode 100644 projects/prisma-8-rc1/parallel-install.md create mode 100644 projects/prisma-8-rc1/release-definition.md create mode 100644 projects/prisma-8-rc1/repo-migration.md create mode 100644 projects/prisma-8-rc1/scoreboard.md diff --git a/projects/prisma-8-rc1/README.md b/projects/prisma-8-rc1/README.md new file mode 100644 index 0000000000..dedcf45425 --- /dev/null +++ b/projects/prisma-8-rc1/README.md @@ -0,0 +1,16 @@ +# Prisma 8 RC1 + +**The goal: on July 31 2026 we publish `prisma@8.0.0-rc.1` from the `prisma/prisma` repository and announce it.** Prisma Next becomes Prisma 8. Users arrive at the same GitHub repository and the same npm package they have always used, and what they find there is the new ORM. + +These documents carry the full context, from the high-level goals down to concrete steps. They deliberately do not say who does what — ownership lives in [Linear](https://linear.app/prisma-company/project/prisma-8-rc1-7592265f700c). + +Read them in order: + +1. **[What the release is](release-definition.md)** — what "RC" means for us, what freezes on July 31, what we promise, and what we deliberately don't. +2. **[How we can tell it's correct](scoreboard.md)** — the feature-support matrix, the side-by-side proof, and the benchmarks. The matrix doubles as the public scoreboard and generates the to-do list. +3. **[The remaining feature set and work](feature-surface.md)** — what ships stable, what ships experimental, what's explicitly out, and the engineering that must land before the freeze. +4. **[The repository and package migration](repo-migration.md)** — the mechanical steps to move into prisma/prisma and onto the `prisma` npm package. +5. **[Running v7 and v8 in parallel](parallel-install.md)** — the incremental migration story we're promising users, and how it actually works. +6. **[The plan](plan.md)** — everything above as dated, ordered steps. + +Decision history and rejected alternatives are in [design-notes.md](design-notes.md). The formal acceptance criteria are in [spec.md](spec.md). diff --git a/projects/prisma-8-rc1/feature-surface.md b/projects/prisma-8-rc1/feature-surface.md new file mode 100644 index 0000000000..362828444e --- /dev/null +++ b/projects/prisma-8-rc1/feature-surface.md @@ -0,0 +1,35 @@ +# The remaining feature set and work + +## What ships at the RC + +The honest answer to "what's in?" is: **that's what the feature-support matrix determines**, and asserting it here in prose would just create a second copy that drifts. The core that all current evidence says is solid: Postgres/SQLite/Mongo targets, the schema language and contract emission, the SQL query builder, the ORM client, transactions, the migration system, and the shipped extensions. The matrix turns that impression into a checked table with a proving suite per cell — see [scoreboard.md](scoreboard.md). + +## What ships experimental + +**Polymorphism (multi-table inheritance and variant relations)** is the candidate. It has an active stream of roughly ten open correctness bugs (variant relations, includes, update/delete predicates, variant resolution). The decision rule, applied July 24: if new bugs have stopped appearing, it ships inside the stability promise; if the stream is still producing, it ships marked experimental and stabilization continues after the RC. This is decided by the bug curve, not by a completion promise. + +## What's known to be out + +Named at matrix freeze, but already known today: + +- **`migration plan --advance`** — documented but not implemented. It sits on the final-cutover step of the v7→v8 migration path, not on the parallel-running path, so it's a tracked public gap for 8.0.0 final rather than an RC blocker. +- **Package consolidation** ("Flavor 2" of the distribution design) — bundling the ~60 internal packages into the main package so they stop being published. Designed, non-breaking, and deliberately deferred past the RC. +- Everything the matrix's deliberate crosses name. + +## Engineering that must land before the freeze + +Each item here changes a surface that freezes on July 31 (see [release-definition.md](release-definition.md)); that's what puts it on this list. + +1. **Error-code consistency.** Today there are four separate error systems with two incompatible code formats — roughly 46 codes shaped like `PN-CLI-4001` and roughly 89 shaped like `RUNTIME.DECODE_FAILED` — plus about sixteen error classes with no code at all (including the SQL driver errors, which are the ones users hit most). One format gets chosen (decision due July 18), everything gets folded into it, errors without codes get codes, and a table maps every old code to its new one. There is deliberately no compatibility with Prisma 7's `P1001`-style codes — the upgrade guide gets a P-code translation table instead. +2. **Rename `extensionPacks` to `extensions`** in the configuration format. Breaking, so now or never. While doing it: sweep the config format for any other key we'd regret freezing as-is. +3. **Fix the connection-pool crash.** A dropped idle connection currently crashes the host process because no error listener is attached. A production-readiness bug, not housekeeping. +4. **Deduplicate migration contract snapshots.** Every migration folder currently stores full copies of the contract; a chain of N migrations stores roughly 2N copies of N+1 distinct contracts. They move to a single `migrations/snapshots/` folder, one file per distinct contract named by its content hash. Migration folders already record which contracts they go from and to, so they need no new link files. This is safe (a migration's identity hash doesn't cover the snapshots, so nothing invalidates) and must happen now (the folder layout freezes at RC). Files stay plain JSON for reviewability, but the reader also accepts gzipped files from day one so compression stays possible later without another format change. +5. **Sweep everything that embeds the old names.** After the package rename, these all still say `prisma-next` unless someone fixes them: the templates that `init` writes into new user projects (dependency names, commands, comments), the user-facing skills that `init` installs, the documentation links embedded in error messages (which must resolve to real pages at RC), and the published upgrade-instruction skills. The old `prisma-next` npm package needs a deprecation notice pointing at `prisma`. And the names that look internal but freeze — environment variables, the per-user config file path, telemetry identifiers — each need an explicit keep-or-rename decision. +6. **Public API documentation comments.** The exported surface of the per-database packages is what users see on hover in their editor. That set — not all 65 packages — gets an audit pass. + +## Quality items that should land before the announcement (but don't freeze) + +- The deprecation warning from the `pg` driver, printed on every connection — a terrible first impression in an otherwise polished RC. +- The open Dependabot security alerts — the announcement puts many eyes on the repository. +- The npm README for the `prisma` package (v8's face on npm) and the "this is an internal package" notices on the implementation packages. +- Announcement-day readiness: confirm the Prisma 7 VS Code extension and the v8 language server don't fight over schema files in a project that has both versions installed; a docs landing page for v8; issue templates that route v7 vs v8 bug reports; verify or soften the Windows, Bun, and Deno support claims; review the telemetry consent prompt and confirm the telemetry backend can take announcement-scale load. diff --git a/projects/prisma-8-rc1/parallel-install.md b/projects/prisma-8-rc1/parallel-install.md new file mode 100644 index 0000000000..9ee88065e9 --- /dev/null +++ b/projects/prisma-8-rc1/parallel-install.md @@ -0,0 +1,64 @@ +# Running v7 and v8 in parallel + +The requirement: **users can run their current Prisma version and Prisma 8 in the same project, against the same database, and migrate incrementally** — new code on v8, old code untouched on v7, cutover at the end. This document is the whole story of how that works. It's also the release's biggest untested claim, which is why it gets an executable proof. + +## What a user's project looks like during migration + +```jsonc +// package.json +{ + "dependencies": { + "prisma-v7": "npm:prisma@^7", // v7 pinned under an alias; existing code keeps working + "prisma": "npm:prisma@next" // resolves to 8.0.0-rc.1 + } +} +``` + +Three things could collide in this setup, and each has an answer: + +**1. Package names.** The npm alias mechanism (shown above) handles library resolution. Beyond the CLI package itself there's no contest: v8 has its own package set and doesn't use `@prisma/client` at all — v8 has no generated client in v7's sense — so all of v7's packages keep their names and their meaning. + +**2. The `prisma` command.** Both versions want to install a binary called `prisma`, and package managers don't resolve that gracefully. Answer: v8's package installs two binaries, `prisma` and `prisma-next`. During coexistence, v7 keeps winning the `prisma` name — so every existing script, CI job, and muscle memory keeps working — and the user drives v8 explicitly as `prisma-next`, the command EA users already use today. When v7 is removed at the end, `prisma` simply starts meaning v8. + +**3. The database schema.** Two migration systems must never both own one schema. The rule is: **v7 keeps owning migrations until one final cutover.** v8 never runs DDL during the transition; it *adopts* the database read-only: + +```bash +prisma-next contract infer # read the live database, derive a matching contract +prisma-next db sign # verify the database satisfies the contract, then record that fact +``` + +`db sign` is deliberately not a "trust me" operation — it first verifies that the live schema actually satisfies the contract and refuses if it doesn't, then writes only a small marker record in v8's own bookkeeping schema (`prisma_contract`), completely separate from v7's `_prisma_migrations` table. The two systems' bookkeeping never touches. + +The routine during the transition, whenever v7 runs a new migration: + +```bash +prisma-next contract infer # re-derive the contract from the changed schema +# review the diff +prisma-next db sign # re-record +``` + +and in CI, `prisma-next db verify --schema-only` confirms the database still matches the contract. One caveat the upgrade guide states plainly: during the transition, verification runs in its default (lenient) mode — strict mode would flag v7's `_prisma_migrations` table as a foreign object, correctly but unhelpfully. + +**The cutover**, when the user is ready: run the last v7 migration, do a final infer-and-sign, remove v7 from the project, and from then on author schema changes in v8 and migrate with v8. (One known gap on this final step — the convenience command for advancing the migration baseline isn't implemented yet; it's a tracked gap for 8.0.0 final, with a documented manual path in the meantime.) + +## The proof + +All of the above is assembled from mechanisms that individually exist and are tested. What has never existed is a single running example of the whole story — the planned side-by-side evaluation on a real app never happened. So we build the proof as an end-to-end fixture in the repository: + +- one project, both versions installed exactly as shown above; +- one Postgres database; +- v7 runs its migrations, seeds data, and keeps querying through v7 code; +- v8 adopts the database, queries the same data, and the results agree; +- v7 runs a *further* migration, and the re-adopt routine (infer → review → sign → verify) is exercised; +- both binaries are invoked by their coexistence names throughout. + +This fixture is the receipt for the announcement's migration claim, a regression test forever after, and the skeleton the upgrade guide's code samples are lifted from. **It must be green by July 24** — if it isn't, the announcement's claim gets scaled back to what's actually proven, and that decision is made at the checkpoint rather than discovered by users. + +## What the upgrade guide covers (written in release week, from the fixture) + +1. The breaking floor: Node 24+, ESM-only, minimum database versions — stated first, because they're the wall a user hits before anything else matters. +2. The parallel-install setup, verbatim from the fixture. +3. The adoption routine and the transition rules (v7 owns migrations; lenient verification; what to do when v7 migrates). +4. The cutover. +5. Error-code translation: a table from Prisma 7's `P1001`-style codes to v8's codes, for migrating runbooks and alerting. +6. The explicit "not in 8.0" list, so nobody discovers an absence in production. diff --git a/projects/prisma-8-rc1/plan.md b/projects/prisma-8-rc1/plan.md index f1f5ef8a89..f6b45f0b6a 100644 --- a/projects/prisma-8-rc1/plan.md +++ b/projects/prisma-8-rc1/plan.md @@ -1,106 +1,83 @@ -# Prisma 8 RC1 — Project Plan +# Prisma 8 RC1 — Plan -## Summary +Everything from the topic documents as dated, ordered steps. Deliberately says nothing about who does what — ownership lives in [Linear](https://linear.app/prisma-company/project/prisma-8-rc1-7592265f700c), where tickets are created as work starts rather than all up front. -Thirteen working days (Jul 15 → Jul 31 2026), three people plus agent capacity, four checkpoint milestones. Slices are grouped by owner lane; sequencing constraints are noted where they exist — everything else runs in parallel. Tickets are created just-in-time when a slice starts, never up-front. +**Context docs:** [README](README.md) · [release definition](release-definition.md) · [scoreboard](scoreboard.md) · [feature surface](feature-surface.md) · [repo migration](repo-migration.md) · [parallel install](parallel-install.md) -**Spec:** [spec.md](spec.md) · **Design notes:** [design-notes.md](design-notes.md) · **Tracking:** [Linear — Prisma 8 RC1](https://linear.app/prisma-company/project/prisma-8-rc1-7592265f700c) +## Starts now — no dependencies -## Checkpoints (Linear milestones) +- Dry-run the history merge in a fork; then create the `v8` branch in prisma/prisma and get CI green on it. +- Start the npm access conversation for the `prisma` package (the only step outside our control) and check `@prisma/postgres` / `@prisma/sqlite` / `@prisma/mongo` for name collisions. +- Build the side-by-side fixture (v7 + v8, one database, v7 owns migrations). Biggest untested claim; needed green by July 24. +- Build the TypeScript compile-time benchmark and its public Bencher dashboard — before the type freeze, while types can still be fixed. +- Enumerate the feature-support matrix rows (v8 surface × Prisma 7 capability census) and draft verdicts; produce the list of "works"-claimed cells with no proving test. +- Deduplicate migration contract snapshots into `migrations/snapshots/` (the folder layout freezes at RC). +- Rename `extensionPacks` → `extensions`, and sweep the config format for other keys we'd regret freezing. +- Fix the connection-pool crash (missing error listeners). +- Continue the polymorphism bug-fixing stream (feeds the July 24 call). -| Date | Milestone | What must be true | -| --- | --- | --- | -| Fri Jul 18 | Error-code scheme ratified | Will decides dotted vs PN-numeric; sweep unblocked | -| Tue Jul 22 | Postgres floor decided | Keep 17 or lower it; supported-surface matrix unblocked | -| Thu Jul 24 | Go/no-go | Polymorphism in/out called; matrix frozen; side-by-side fixture green (or the coexistence claim is softened) | -| Thu Jul 31 | RC1 published & announced | Release-week mechanicals complete; announcement live | +## Fri July 18 — decision: error-code format -## Lane: Will — merge, ops, decisions +Choose between the dotted format (`RUNTIME.DECODE_FAILED`, ~89 codes) and the prefixed-numeric format (`PN-CLI-4001`, ~46 codes). Recommendation on the table: dotted wins. The decision unblocks: -### Slice W1: v8 branch + CI in prisma/prisma — **critical path, start immediately** +- The error consolidation: fold all four error systems into the chosen format, give codes to the ~16 codeless error classes, publish the old→new mapping table. Codes freeze at RC; message wording can keep improving after. -Merge prisma-next content onto a `v8` branch in `prisma/prisma`; get the full CI suite green there and keep it green for the rest of the project. Includes deciding the history graft (v7 history under main vs parallel histories) via a dry run in a fork first. Merge to `main` happens in release week (W4), not before. +## Tue July 22 — decision: minimum Postgres version -### Slice W2: npm ops on the `prisma` package — **critical path, external dependency, chase first** +Keep the Postgres 17 floor (it was an early-access-era convenience) or lower it for the migrating audience. Every supported version is a CI matrix row forever. The decision unblocks final matrix verdicts for version-sensitive cells. -Obtain publish rights and OIDC trusted-publisher configuration on the `prisma` npm package; confirm v7's release automation tolerates a second publisher under a different dist-tag. Also: collision audit of the visible rename set (`@prisma/postgres`, `@prisma/sqlite`, `@prisma/mongo`) against classic-owned `@prisma/*` names. +## Wed July 23 — quality sweep target -### Slice W3: decisions +Aim to have landed by here (all independent, none block anything): -Error-code scheme (Jul 18), Postgres floor (Jul 22), polymorphism go/no-go (Jul 24). Each unblocks a slice below. +- The old-name sweep: `init` templates, installed user skills, upgrade skills, documentation links inside error messages, deprecation notice on the old `prisma-next` package, and keep-or-rename decisions on env vars / config paths / telemetry identifiers. +- Documentation-comment audit of the per-database packages' exported surface. +- The `pg` driver deprecation warning; the open Dependabot alerts; the npm README for `prisma`. +- Port the highest-value Prisma 7 test cases against the matrix's unproven-cells list (continues afterward; this is a stream, not a single step). -### Slice W4: release week mechanicals (Jul 28–31) +## Thu July 24 — the go/no-go checkpoint -Lockstep version to `8.0.0-rc.1` (`set-version`); visible-set rename (shim → `prisma`, facades → `@prisma/*`); `v7` maintenance branch cut with CI; merge v8 branch → main; issue-close sweep with pinned explanation issue and saved reply; publish under non-`latest` dist-tag; announcement live. +Three calls, made in writing: -### Slice W5: announcement + upgrade guide +1. **Polymorphism: stable or experimental.** Rule: new bugs stopped appearing → stable; still appearing → experimental, work continues post-RC. +2. **Matrix verdicts freeze.** Every cell now reads works-with-proof, experimental, or not-in-8.0. +3. **Side-by-side fixture green?** If not, scale the announcement's migration claim back to what's proven. -Leads with Node ≥24 + ESM-only as headline breaking changes; parallel-install recipe (mirroring the fixture); 12-months-from-final v7 statement; supported-surface matrix; explicit not-in-8.0 list; links to Bencher. +After this day, no scope moves — only execution. -## Lane: Will (agent-executed) — mechanical engineering, lands as bot PRs +## Fri July 25 — announcement-day readiness -### Slice A1: TS performance benchmark harness — **first dispatch, before the type freeze** +- Announcement and upgrade guide drafted (guide's code samples lifted from the fixture). +- VS Code: confirm the v7 extension and the v8 language server coexist in a dual-install project. +- Docs landing page for v8 exists; issue templates route v7-vs-v8 reports; first-response plan for launch week. +- Verify or soften the Windows / Bun / Deno claims; review the telemetry consent prompt and backend capacity. -Bench package generating synthetic schemas at 10/100/500 models; runs `tsc --extendedDiagnostics` across v8 under TS 5.9 and TS 7; emits Bencher BMF JSON per CI run to a **public Bencher project**. PR regression check fails on type-instantiation counts (deterministic); wall time and memory tracked as informational trend. One internal v7 comparison run sanity-checks the announcement wording — never published. +## Mon July 28 – Thu July 31 — release week -### Slice A2: migration contract-snapshot centralization — **pre-freeze (migrations/ layout freezes at RC)** +In order: -Centralize per-migration contract copies into content-addressed `migrations/snapshots/.json`. Migration dirs reference contracts via the from/to hashes already in `migration.json`; the contract-reference resolver learns the snapshot store; emitter updated; example migrations regenerated. Safe because ADR 199 excludes snapshots from migration identity. Writer emits plain JSON; reader accepts `.json.gz` from day one (compression stays a future non-breaking option). +1. Version everything to `8.0.0-rc.1` (lockstep, one command). +2. Rename the CLI package to `prisma` and the three per-database packages to `@prisma/*`; configure trusted publishing for the new names. +3. Cut the `v7` maintenance branch with working CI. +4. Merge `v8` into `main`. +5. Close old v7 issues/PRs except v7 bugs; pin the explanation issue. +6. Re-run the runtime benchmarks; confirm the published numbers still hold. +7. Render and publish the feature matrix (the public scoreboard). +8. Publish under the non-`latest` dist-tag; verify `npm install prisma` still yields v7 and the RC tag yields v8 with both binaries working. +9. Deprecation notice on the old `prisma-next` package. +10. **Announce.** -### Slice A3: error-code consistency sweep — **blocked on W3 scheme decision (Jul 18)** +## After the RC (road to 8.0.0 final) -Fold the four error models into the ratified scheme: fold in the ~16 codeless classes (SQL driver errors, bespoke tail, the duplicated `ContractValidationError`), normalize the losing format, build the central factory/registry ADR 027 assumes, publish the crosswalk. Codes freeze at RC; conformance/golden tests may trail. - -### Slice A4: `extensionPacks` → `extensions` rename (TML-2462) — **pre-freeze** - -Breaking config-key rename; must precede the API freeze. Record upgrade instructions per the breaking-change workflow. - -### Slice A5: Pool error-listener fix (TML-2655) - -Idle-reconnect errors crash the host process; production-readiness fix, not cleanup. - -### Slice A6: supported-surface matrix as structured data — **start now; only the freeze waits on decisions** - -Feature area × database target × status (`stable` / `experimental` / `not-in-8.0`), as checked-in structured data. Every `stable` cell names the test suite that proves it; every `not-in-8.0` cell is a deliberate statement, not an omission. - -**Where the rows come from — two sources, crossed:** - -1. *What v8 ships*, enumerated from the codebase: facade subpath exports (`@prisma-next/{postgres,sqlite,mongo}`), the CLI command tree, the PSL feature set (attributes, types, namespaces), the ORM/query-builder operation surface, the migration operation catalog, and the extensions. If it isn't reachable through the blessed surface, it isn't a row. -2. *What v7 users expect*: Prisma 7's capability taxonomy (docs navigation + the functional test suite's directory structure, which is a de-facto feature census). This is the completeness checklist that makes "missing capabilities are named" true — absence can only be named against an enumeration of what users look for. - -**Phase 1 (now, no dependencies):** enumerate rows, draft cell statuses, and list every stable-claimed cell with no proving suite — that list is S2's mining work-list. - -**Phase 2 (freeze at Jul 24):** stamp final statuses once the Postgres floor (Jul 22) and the polymorphism call (Jul 24) land. - -Feeds the S2 filter, the announcement's supported-surface section, and the post-RC public dashboard. - -## Lane: Serhii — coexistence proof + correctness - -### Slice S1: side-by-side fixture — **top risk, start immediately, zero dependencies** - -One repo, both versions installed (npm alias for v7), one Postgres database, v7 owning DDL. Exercises: initial adoption (`contract infer` → `db sign`), the standing loop after a v7 migration (re-infer → re-sign → `db verify --schema-only`), and dual-client queries against the same data. The Dub.co side-by-side evaluation (WS1 M4) never ran, so this fixture is the first-ever test of the RC's central claim. Must be green by Jul 24. - -### Slice S2: P7 test mining — **after S1, filtered by A6** - -Mine (don't convert) the P7 functional suite: extract the database and relational-algebra edge cases it encodes, scoped to what the matrix claims is stable, into `test/integration/` + `test/e2e/` following the existing per-target patterns. The fixture from S1 doubles as the differential harness where v7-as-oracle comparison is cheaper than porting assertions. - -## Lane: Alexey — polymorphism - -### Slice X1: MTI/variant-relation stabilization - -The ~10 active correctness bugs in SQL ORM polymorphism (variant relations, includes, update/delete predicates, namespace-flat variant resolution). The bug-discovery curve — not a completion promise — decides the Jul 24 call: flattened → in scope at RC; still producing → ships marked experimental and the stream continues post-RC. - -## Sequencing constraints (everything else is parallel) - -- W2 (npm rights) blocks nothing until release week, but its *external* nature means it starts first. -- W3 decisions block A3 (scheme) and A6 *phase 2 only* (floor + polymorphism call); A6 phase 1 blocks nothing and starts now. -- A6 phase 1's no-proving-suite list is S2's work-list; S1 must be green by Jul 24 or the coexistence claim in W5 is softened. -- A1, A2, A4, A5, A6 phase 1, S1, X1 have no upstream dependencies — all start immediately. -- W4 is strictly last and consumes everything. +- Nightly runtime benchmarks in CI (about a day to make reliable — spent now that it doesn't compete with the release). +- The public matrix page drives the road-to-final story: crosses flip to ticks; gaps get tracked issues on an `8.0.0` milestone. +- Implement `migration plan --advance` (the cutover convenience command). +- Package consolidation (stop publishing the ~60 internal packages). +- Biweekly public status updates until final. Final ships on criteria, not a date: every cell proven or excluded, the migration fixture green, a quiet period with no new blockers. ## Close-out (required) - [ ] Verify all acceptance criteria in [spec.md](spec.md) -- [ ] Migrate long-lived docs into `docs/` (upgrade guide, coexistence workflow, error-code scheme ADR + crosswalk, snapshot-layout ADR, supported-surface matrix home) +- [ ] Migrate long-lived docs into `docs/` (upgrade guide, coexistence workflow, error-code scheme + crosswalk, snapshot layout, the matrix's permanent home) - [ ] Strip repo-wide references to `projects/prisma-8-rc1/**` - [ ] Final retro; delete `projects/prisma-8-rc1/` diff --git a/projects/prisma-8-rc1/release-definition.md b/projects/prisma-8-rc1/release-definition.md new file mode 100644 index 0000000000..efd55078d9 --- /dev/null +++ b/projects/prisma-8-rc1/release-definition.md @@ -0,0 +1,40 @@ +# What the release is + +## The release + +On July 31 2026 we publish **`prisma@8.0.0-rc.1`** — Prisma Next, versioned as Prisma 8, released from the merged `prisma/prisma` repository — and announce it publicly the same day. + +It is a release candidate, not a final release. That distinction does the most important work in this whole plan: **a release candidate freezes the API surface; it does not promise completeness.** Our bar is not "Prisma 8 can do everything Prisma 7 can do." Our bar is: everything we ship works, we can prove it, and everything we don't ship is named explicitly rather than discovered in production. + +The version number is 8 (we considered 10 to signal a bigger jump, and rejected it — the architecture and the marketing already tell the discontinuity story, and a skipped version number is permanent confusion for no gain). + +## What freezes on July 31 + +Once the RC is out, users write code, scripts, and runbooks against it. These surfaces therefore cannot change between RC and 8.0.0 final, which means all changes to them must land before July 31: + +- **Package names.** The `prisma` package and the per-database packages users import. +- **The CLI.** Command names, flags, and the names of the installed binaries. +- **Error codes.** Users write `catch` logic and alerting rules against them. +- **Configuration keys.** For example the `extensionPacks` key, which is being renamed to `extensions` — that rename must happen now or never. +- **The `migrations/` folder layout.** Users commit this folder to their repositories and tools read it. The planned deduplication of contract snapshots inside it must land before the RC. +- **Emitted artifact formats.** `contract.json` and `contract.d.ts`. +- **Version floors.** Minimum supported Node.js, TypeScript, and database versions. +- **Names that look internal but aren't.** Environment variable names, the per-user config file path, telemetry identifiers. Each needs an explicit keep-or-rename decision before the freeze, because after it they're permanent. + +Anything not on this list — message wording, documentation, additional tests, performance improvements, internal package structure — can keep changing after the RC. + +## What we promise at the RC + +1. **Nobody gets v8 by accident.** The RC publishes under a dist-tag other than `latest`, so `npm install prisma` continues to install Prisma 7 until 8.0.0 final ships. +2. **API stability from RC 1**, with the experimental parts named explicitly. The experimental list is what protects the stability promise. +3. **Prisma 7 is maintained for 12 months, counted from the day 8.0.0 final ships** (not from the RC — if final slips, the promise must not silently shrink). Bug fixes on a `v7` branch; this window is stated in the announcement. +4. **v7 and v8 run side by side in one project**, so migration can be incremental. This claim gets its own document: [parallel-install.md](parallel-install.md). +5. **A public scoreboard instead of promises.** The feature-support matrix (see [scoreboard.md](scoreboard.md)) shows exactly what works where, what's experimental, and what's not in 8.0. +6. **Promotion criteria instead of a date for 8.0.0 final.** Final ships when every matrix cell is either proven or explicitly excluded, the migration recipe passes its test, and a quiet period passes with no new release blockers. We give a target window, never per-feature dates. + +## What we deliberately do not promise + +- Prisma 7 feature parity. +- A stability guarantee for features marked experimental. +- Runtime performance numbers beyond what's already published (the comparison benchmarks are public; before tagging the RC we re-run them to confirm they still hold). +- A renamed GitHub organization or repository (`prisma/prisma-orm` was considered and parked — GitHub redirects make it cheap to do at any later point). diff --git a/projects/prisma-8-rc1/repo-migration.md b/projects/prisma-8-rc1/repo-migration.md new file mode 100644 index 0000000000..45a97d113e --- /dev/null +++ b/projects/prisma-8-rc1/repo-migration.md @@ -0,0 +1,47 @@ +# The repository and package migration + +The mechanical half of the release: moving the code into `prisma/prisma`, and taking over the `prisma` name on npm without breaking anyone. + +## Target shape + +``` +prisma/prisma +├── main ← becomes Prisma Next (after the final merge) +├── v8 ← staging branch until release week +└── v7 ← Prisma 7 maintenance (bug fixes, 12 months from 8.0.0 final) + +tags: v7.x.y (existing) · v8.0.0-rc.1 · v8.0.0 (later) +``` + +On npm: + +- **`prisma`** — becomes the Prisma 8 CLI package (a thin, binary-only package; importing it is deliberately an error). The RC publishes under a dist-tag other than `latest`, so `npm install prisma` keeps installing v7 until 8.0.0 final. +- **`@prisma/postgres`, `@prisma/sqlite`, `@prisma/mongo`** — the per-database packages users import, renamed from `@prisma-next/*`. These are the *only* scoped packages that get renamed: they plus the CLI are the entire supported import surface, so renaming just them keeps the frozen-name set small. +- **All other `@prisma-next/*` packages** (~60 of them) — unchanged. They're implementation detail, installed transitively. A later, non-breaking consolidation bundles them into the CLI package and stops publishing them; that's explicitly after the RC. +- **The old `prisma-next` package** — gets a deprecation notice pointing users at `prisma`. + +The CLI installs two binaries: `prisma` and `prisma-next`. This is the parallel-install answer (see [parallel-install.md](parallel-install.md)): in a project that has both versions, v7 keeps owning the `prisma` command so existing scripts don't break, and users drive v8 as `prisma-next` — the command EA users already know — until they remove v7. + +## Concrete steps + +### Now (longest lead items, in parallel) + +1. **Dry-run the history merge in a fork.** Decide how v7 history and prisma-next history combine (graft vs parallel histories), execute it in a fork, and check the result: log readability, blame, tags, repository size. +2. **Create the `v8` branch in prisma/prisma** from the dry-run recipe and get the full CI suite green on it. It stays green from now until release week — merge mechanics must never be a last-week discovery. +3. **Start the npm access conversation.** The `prisma` package is currently published by Prisma 7's release pipeline. We need: publish permission for our pipeline on that package, its trusted-publisher (OIDC) configuration extended to our workflow, and confirmation that v7's automation won't be disturbed by an RC appearing under another dist-tag. This is the one step controlled by people outside the project, which is why it starts on day one. +4. **Check name availability.** Confirm `@prisma/postgres`, `@prisma/sqlite`, and `@prisma/mongo` don't collide with anything classic Prisma already publishes under `@prisma/*` (it owns many names there: `client`, `config`, `engines`, the `adapter-*` family, …). + +### Release week (July 28–31) + +5. **Version everything to `8.0.0-rc.1`.** One command — the repository versions all packages in lockstep. +6. **Execute the rename** of the CLI package and the three per-database packages, including their trusted-publisher configuration (it's per-package, and renamed packages count as new). +7. **Cut the `v7` branch** with working CI. +8. **Merge `v8` into `main`.** +9. **Triage the open v7 issues and pull requests.** Close everything except v7 bug reports; post a pinned issue explaining the change and use a saved reply linking to it. This deliberately happens at merge time, not earlier — doing it before there's an announcement to point at just generates weeks of confusion. +10. **Publish** under the non-`latest` dist-tag. Verify: `npm install prisma` still yields v7; installing the RC tag yields v8; both binaries work. +11. **Deprecation notice** on the old `prisma-next` package. +12. **Announce.** + +## Explicitly parked + +Renaming the repository or organization (e.g. `prisma/prisma-orm`, to decouple the company name from the ORM). GitHub redirects make this cheap at any time, so it doesn't need to share a window with everything above. diff --git a/projects/prisma-8-rc1/scoreboard.md b/projects/prisma-8-rc1/scoreboard.md new file mode 100644 index 0000000000..4dcd655ad0 --- /dev/null +++ b/projects/prisma-8-rc1/scoreboard.md @@ -0,0 +1,52 @@ +# How we can tell it's correct + +The release bar is "everything we ship works." This document is about making that a checkable statement instead of a feeling. The principle throughout: **every claim in the announcement has a receipt** — a test suite, a fixture, or a published measurement that anyone can look at. + +## The feature-support matrix + +The centerpiece. A table with one row per feature and one column per database (Postgres, SQLite, MongoDB). Every cell holds one of three verdicts: + +- **Works** — and the cell names the test suite that proves it. A "works" without a green suite behind it is not allowed on the board. +- **Experimental** — shipped, usable, explicitly outside the stability promise. +- **Not in 8.0** — a deliberate, written-down absence. + +### Where the rows come from + +You cannot name what's missing by looking only at what you built. So the row list is built by crossing two enumerations: + +1. **What v8 actually exposes**, read out of the codebase: the exports of the per-database packages, the CLI's command tree, the PSL schema-language feature set, the query and ORM operations, the migration operations, and the extensions. If a capability isn't reachable through the supported public surface, it isn't a row. +2. **What Prisma 7 users will look for**, read out of Prisma 7's documentation structure and its functional test suite (which is effectively a census of every feature P7 ever supported): relation kinds, JSON operations, full-text search, views, multi-schema, raw queries, transaction variants, and so on. This list is what forces every absence to be named instead of silently missing. + +### What the matrix produces + +Three things, from one artifact: + +- **The public dashboard.** The matrix is checked into the repository as structured data and rendered by CI as a page of ticks and crosses. There is no separate progress dashboard: cells flipping from cross to tick as their proving suites go green *is* the progress display, both for us before the RC and for the public after it. Ticks link to the proving suite; deliberate crosses become the "not in 8.0" list and, after the RC, link to gap-tracking issues. +- **The to-do list.** Every cell we believe works but that no current test proves is, by definition, missing test coverage. That list of unproven cells is the work queue for the test-porting effort below. +- **The announcement's supported-surface section**, generated rather than hand-written. + +### Timing + +Enumerating rows and drafting verdicts needs no decisions and starts immediately. Final verdicts are stamped at the July 24 checkpoint, after the minimum-Postgres-version decision (July 22) and the polymorphism stable-or-experimental call (July 24). + +## The side-by-side proof + +The single biggest claim in the release is that v7 and v8 run together in one project against one database so users can migrate incrementally. **Nobody has ever actually run this setup** — the evaluation that was planned for it never happened. So we build it as an end-to-end test fixture: both versions installed in one project, one Postgres database, v7 continuing to run its migrations while v8 adopts the same database and queries it, including the routine of re-adopting after v7 changes the schema. + +This fixture must be green by July 24. If it isn't, the parallel-install claim in the announcement gets softened — that trade is decided at the checkpoint, not discovered after launch. Details of what it exercises are in [parallel-install.md](parallel-install.md). + +## Mining Prisma 7's tests + +Prisma 7's functional test suite encodes years of accumulated database and query edge cases — that accumulated knowledge is the valuable artifact, not the test code itself, which is written against a different API and would take months to convert wholesale. So instead of converting it, we mine it: extract the cases that cover features our matrix claims work but that no current v8 test proves (the unproven-cell list above), and port just those. Where checking against v7's behavior is cheaper than porting assertions, the side-by-side fixture doubles as the comparison harness: run the same scenario through both versions and compare results, with v7 as the reference. + +With EA adoption having been thin, this suite does the confidence-building work that production feedback would normally do. + +## Benchmarks + +**TypeScript compile-time performance** is measured before the type freeze, not after — v8's types lean heavily on conditional types, which is exactly the pattern that can make type-checking slow on large schemas, and if the numbers are bad, the types can only be fixed while they're still allowed to change. The benchmark generates schemas of 10, 100, and 500 models, measures `tsc` check time, type-instantiation counts, and memory, on both TypeScript 5.9 and TypeScript 7, and publishes every run to a public Bencher dashboard. Pull requests fail if they increase instantiation counts (chosen as the merge-blocking metric because it's deterministic; wall-clock time on shared CI runners is too noisy to block on and is tracked as a trend instead). + +**Runtime performance** comparisons against v7 are already published, with graphs. Two follow-ups: before tagging the RC, the suite is re-run manually to confirm the published numbers still hold — having published the claim, the one unshippable thing is an RC that quietly walks it back. After the RC, the suite gets a day of engineering to run reliably in CI on a nightly schedule (nightly rather than per-PR: runtime benchmarks on shared runners are too flaky to block merges on, and a nightly trend with alerts gives the regression protection without ever blocking anyone). + +## The checkpoint + +July 24 is the day all of this converges. Three calls get made, in writing: polymorphism ships stable or experimental (decided by whether new bugs have stopped appearing); the matrix verdicts freeze; and the side-by-side fixture is green or the coexistence claim is cut down to what's actually proven. After July 24, everything remaining is mechanical. From 4493d2166de14c5e78234c39fe9bc1abdbd01903 Mon Sep 17 00:00:00 2001 From: willbot Date: Thu, 16 Jul 2026 10:10:13 +0200 Subject: [PATCH 5/8] docs(drive): registry permissions already held; clarify what Flavor 2 defers Publish access to the prisma package exists, so the registry step is release-week configuration, not an external dependency. The critical path reduces to the merge branch and the side-by-side fixture. Also spell out that the small four-package public API ships at RC (facade parity landed in May); only the bundling of internals is deferred. Signed-off-by: willbot Signed-off-by: Will Madden --- projects/prisma-8-rc1/feature-surface.md | 2 +- projects/prisma-8-rc1/plan.md | 2 +- projects/prisma-8-rc1/repo-migration.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/projects/prisma-8-rc1/feature-surface.md b/projects/prisma-8-rc1/feature-surface.md index 362828444e..a85e8f72a1 100644 --- a/projects/prisma-8-rc1/feature-surface.md +++ b/projects/prisma-8-rc1/feature-surface.md @@ -13,7 +13,7 @@ The honest answer to "what's in?" is: **that's what the feature-support matrix d Named at matrix freeze, but already known today: - **`migration plan --advance`** — documented but not implemented. It sits on the final-cutover step of the v7→v8 migration path, not on the parallel-running path, so it's a tracked public gap for 8.0.0 final rather than an RC blocker. -- **Package consolidation** ("Flavor 2" of the distribution design) — bundling the ~60 internal packages into the main package so they stop being published. Designed, non-breaking, and deliberately deferred past the RC. +- **Package consolidation** ("Flavor 2" of the distribution design) — bundling the ~60 internal packages into the main package so they stop being published. To be clear about what is and isn't deferred here: the *small public API* — users interact with exactly four packages (the CLI plus the three per-database packages), and never import an internal name — is already true (facade re-export parity shipped in May, TML-2526) and is part of the RC. What's deferred is only how the box is packed: whether internal code arrives as ~60 transitively-installed packages or bundled inside the main package, which users can't observe. Bundling is publish-pipeline surgery that doesn't belong in the release window. If the matrix enumeration finds any capability that leaked outside the facades since May, closing that gap *is* RC scope — the facades must be complete at the freeze. - Everything the matrix's deliberate crosses name. ## Engineering that must land before the freeze diff --git a/projects/prisma-8-rc1/plan.md b/projects/prisma-8-rc1/plan.md index f6b45f0b6a..5502a0e6e5 100644 --- a/projects/prisma-8-rc1/plan.md +++ b/projects/prisma-8-rc1/plan.md @@ -7,7 +7,7 @@ Everything from the topic documents as dated, ordered steps. Deliberately says n ## Starts now — no dependencies - Dry-run the history merge in a fork; then create the `v8` branch in prisma/prisma and get CI green on it. -- Start the npm access conversation for the `prisma` package (the only step outside our control) and check `@prisma/postgres` / `@prisma/sqlite` / `@prisma/mongo` for name collisions. +- Check `@prisma/postgres` / `@prisma/sqlite` / `@prisma/mongo` for name collisions. (Publish permissions on the `prisma` package are already held; the remaining trusted-publisher configuration is release-week work.) - Build the side-by-side fixture (v7 + v8, one database, v7 owns migrations). Biggest untested claim; needed green by July 24. - Build the TypeScript compile-time benchmark and its public Bencher dashboard — before the type freeze, while types can still be fixed. - Enumerate the feature-support matrix rows (v8 surface × Prisma 7 capability census) and draft verdicts; produce the list of "works"-claimed cells with no proving test. diff --git a/projects/prisma-8-rc1/repo-migration.md b/projects/prisma-8-rc1/repo-migration.md index 45a97d113e..d6d869cecf 100644 --- a/projects/prisma-8-rc1/repo-migration.md +++ b/projects/prisma-8-rc1/repo-migration.md @@ -28,7 +28,7 @@ The CLI installs two binaries: `prisma` and `prisma-next`. This is the parallel- 1. **Dry-run the history merge in a fork.** Decide how v7 history and prisma-next history combine (graft vs parallel histories), execute it in a fork, and check the result: log readability, blame, tags, repository size. 2. **Create the `v8` branch in prisma/prisma** from the dry-run recipe and get the full CI suite green on it. It stays green from now until release week — merge mechanics must never be a last-week discovery. -3. **Start the npm access conversation.** The `prisma` package is currently published by Prisma 7's release pipeline. We need: publish permission for our pipeline on that package, its trusted-publisher (OIDC) configuration extended to our workflow, and confirmation that v7's automation won't be disturbed by an RC appearing under another dist-tag. This is the one step controlled by people outside the project, which is why it starts on day one. +3. **npm publish configuration.** We already hold publish permissions on the `prisma` package, so nothing here waits on anyone outside the project. What remains is config work: extend the package's trusted-publisher (OIDC) configuration to our publish workflow once it lives in prisma/prisma, do the same for the renamed database packages (trusted publishing is per-package, and renamed packages count as new), and do one dry-run publish under a throwaway dist-tag to confirm v7's release automation is undisturbed. 4. **Check name availability.** Confirm `@prisma/postgres`, `@prisma/sqlite`, and `@prisma/mongo` don't collide with anything classic Prisma already publishes under `@prisma/*` (it owns many names there: `client`, `config`, `engines`, the `adapter-*` family, …). ### Release week (July 28–31) From 5db841deb615d27322882c6c40d535eb4aaac803 Mon Sep 17 00:00:00 2001 From: willbot Date: Thu, 16 Jul 2026 10:26:14 +0200 Subject: [PATCH 6/8] docs(drive): the RC ships a single prisma-next binary, no prisma bin Bin-name collisions between two installed packages resolve differently per package manager, so coexistence must not depend on v7 winning one. With only prisma-next declared there is no collision: prisma means v7 everywhere until v7 is removed. Whether v8 ever adds a bare prisma binary is deferred to the road to final; adding a bin later is additive. Signed-off-by: willbot Signed-off-by: Will Madden --- projects/prisma-8-rc1/design-notes.md | 3 ++- projects/prisma-8-rc1/parallel-install.md | 2 +- projects/prisma-8-rc1/plan.md | 2 +- projects/prisma-8-rc1/repo-migration.md | 4 ++-- projects/prisma-8-rc1/spec.md | 2 +- 5 files changed, 7 insertions(+), 6 deletions(-) diff --git a/projects/prisma-8-rc1/design-notes.md b/projects/prisma-8-rc1/design-notes.md index 4d36640d07..4d403ec176 100644 --- a/projects/prisma-8-rc1/design-notes.md +++ b/projects/prisma-8-rc1/design-notes.md @@ -17,7 +17,7 @@ The v8 branch lands in `prisma/prisma` immediately and runs full CI for weeks; m ## Parallel install: three collision surfaces, three answers 1. **npm names.** No collisions: Prisma Next has its own package set and no client in v7's sense, so `@prisma/client` stays v7-only. Library-level coexistence is the documented alias pattern (`"prisma-v7": "npm:prisma@^7"`). -2. **The CLI bin.** Both packages want a bin named `prisma`. Resolution: v8's `prisma` package ships **two bins — `prisma` and `prisma-next`** — and during coexistence v7 keeps winning `prisma`, so existing scripts and CI never break; users drive v8 explicitly via `prisma-next` (which EA users already type). At cutover, v7 is removed and `prisma` points at v8. `prisma8` was considered and dropped: `prisma-next` already exists, is already in muscle memory, and avoids migrating users' habits twice. Long-term CLI home (`@prisma/cli`, prisma/prisma-cli) is compatible with this and out of scope. +2. **The CLI bin.** v8's `prisma` package ships **exactly one binary: `prisma-next`** — it deliberately does not declare a `prisma` bin at RC. Reasoning: when two installed packages declare the same binary name, which one wins `node_modules/.bin` is package-manager-specific and effectively undocumented, so a coexistence story that depends on "v7 wins the collision" is nondeterministic across npm/pnpm/Yarn/Bun. With only `prisma-next` declared, there is no collision at all: `prisma` unambiguously means v7 on every package manager until v7 is removed. Whether v8 ever adds a bare `prisma` binary (at 8.0.0 final, or later via `@prisma/cli`) is deliberately deferred — v8's commands share nothing with v7's, so v7 muscle memory doesn't transfer regardless of the binary's name, and adding a bin later is purely additive. 3. **Migration ownership.** Two migration systems must never both mutate one schema. **v7 owns migrations until a single final cutover.** v8 adopts the database read-only via the shipped, e2e-tested brownfield path (ADR 122): `contract infer` → `db sign` (which verifies the live schema satisfies the contract before writing anything, then records only a marker in the reserved `prisma_contract` schema — it never touches `_prisma_migrations`). After each v7 migration during coexistence: re-infer, review the diff, re-sign; `db verify --schema-only` in CI. At cutover: final sign against the last v7-migrated state, then normal v8 migration flow. **Known wrinkle:** v7 puts `_prisma_migrations` in `public`, so it is an "unclaimed element" to v8 — tolerated by default `db verify`, but a failure under `--strict` and flagged by `db init`. The upgrade guide blesses **lenient mode until cutover** (one paragraph) rather than building an ignore/allowlist mechanism (a feature nobody needs after the transition). @@ -65,6 +65,7 @@ Will (lead: merge, npm ops, decisions, announcement, and the agent-executed engi - **Reusing classic P-codes (P1001-style)** — rejected: zero compatibility exists in the codebase by design; retrofitting would break EA users to please v7 muscle memory. A mapping table in the upgrade guide serves the runbook crowd instead. - **`prisma8` as the coexistence bin** — rejected in favor of keeping `prisma-next`: it already exists and EA users already use it; no second habit migration. - **v8 claiming the `prisma` bin during coexistence** — rejected: breaks every existing v7 script and CI job on install. +- **v8 shipping both `prisma` and `prisma-next` bins ("v7 wins the collision")** — rejected, superseding an earlier version of this plan: bin-collision winners are package-manager-specific and undocumented, so the coexistence behavior would be nondeterministic. The RC ships `prisma-next` only. - **Both migration systems owning DDL** — rejected: requires reconciliation machinery that doesn't exist; single-owner-until-cutover is the shipped, tested model. - **An ignore/allowlist mechanism for v7's `_prisma_migrations` under `db verify --strict`** — rejected for now: lenient-mode guidance is one paragraph; the allowlist is a feature with a lifespan of one transition. - **Renaming all 65 packages to `@prisma/*` at RC** — rejected: blesses ~65 names as frozen public API; only the visible set (shim + facades) is user-facing per ADR 211. diff --git a/projects/prisma-8-rc1/parallel-install.md b/projects/prisma-8-rc1/parallel-install.md index 9ee88065e9..5cb3d2deda 100644 --- a/projects/prisma-8-rc1/parallel-install.md +++ b/projects/prisma-8-rc1/parallel-install.md @@ -18,7 +18,7 @@ Three things could collide in this setup, and each has an answer: **1. Package names.** The npm alias mechanism (shown above) handles library resolution. Beyond the CLI package itself there's no contest: v8 has its own package set and doesn't use `@prisma/client` at all — v8 has no generated client in v7's sense — so all of v7's packages keep their names and their meaning. -**2. The `prisma` command.** Both versions want to install a binary called `prisma`, and package managers don't resolve that gracefully. Answer: v8's package installs two binaries, `prisma` and `prisma-next`. During coexistence, v7 keeps winning the `prisma` name — so every existing script, CI job, and muscle memory keeps working — and the user drives v8 explicitly as `prisma-next`, the command EA users already use today. When v7 is removed at the end, `prisma` simply starts meaning v8. +**2. The `prisma` command.** When two installed packages declare the same binary name, which one wins is package-manager-specific and effectively undocumented — not something to build a migration story on. So there is no contest to resolve: **v8's package installs exactly one binary, `prisma-next`.** The `prisma` command always means v7, on every package manager, for as long as v7 is installed; v8 is always `prisma-next`, the command EA users already use today. Existing scripts and CI jobs keep working untouched. Whether a bare `prisma` binary ever ships for v8 — at 8.0.0 final or later via `@prisma/cli` — is deliberately left open; adding a binary later is purely additive, so deferring the decision costs nothing. **3. The database schema.** Two migration systems must never both own one schema. The rule is: **v7 keeps owning migrations until one final cutover.** v8 never runs DDL during the transition; it *adopts* the database read-only: diff --git a/projects/prisma-8-rc1/plan.md b/projects/prisma-8-rc1/plan.md index 5502a0e6e5..1aa3ddbebe 100644 --- a/projects/prisma-8-rc1/plan.md +++ b/projects/prisma-8-rc1/plan.md @@ -63,7 +63,7 @@ In order: 5. Close old v7 issues/PRs except v7 bugs; pin the explanation issue. 6. Re-run the runtime benchmarks; confirm the published numbers still hold. 7. Render and publish the feature matrix (the public scoreboard). -8. Publish under the non-`latest` dist-tag; verify `npm install prisma` still yields v7 and the RC tag yields v8 with both binaries working. +8. Publish under the non-`latest` dist-tag; verify `npm install prisma` still yields v7 and the RC tag yields v8 with the `prisma-next` binary working (and no `prisma` binary declared). 9. Deprecation notice on the old `prisma-next` package. 10. **Announce.** diff --git a/projects/prisma-8-rc1/repo-migration.md b/projects/prisma-8-rc1/repo-migration.md index d6d869cecf..a945abb701 100644 --- a/projects/prisma-8-rc1/repo-migration.md +++ b/projects/prisma-8-rc1/repo-migration.md @@ -20,7 +20,7 @@ On npm: - **All other `@prisma-next/*` packages** (~60 of them) — unchanged. They're implementation detail, installed transitively. A later, non-breaking consolidation bundles them into the CLI package and stops publishing them; that's explicitly after the RC. - **The old `prisma-next` package** — gets a deprecation notice pointing users at `prisma`. -The CLI installs two binaries: `prisma` and `prisma-next`. This is the parallel-install answer (see [parallel-install.md](parallel-install.md)): in a project that has both versions, v7 keeps owning the `prisma` command so existing scripts don't break, and users drive v8 as `prisma-next` — the command EA users already know — until they remove v7. +The CLI installs exactly one binary: `prisma-next`. It does not declare a `prisma` binary — bin-name collisions between two installed packages resolve differently per package manager, so during coexistence `prisma` must unambiguously mean v7 (see [parallel-install.md](parallel-install.md)). Whether v8 ever ships a bare `prisma` command — at 8.0.0 final or later via `@prisma/cli` — is an open road-to-final decision; adding a binary is additive whenever it happens. ## Concrete steps @@ -38,7 +38,7 @@ The CLI installs two binaries: `prisma` and `prisma-next`. This is the parallel- 7. **Cut the `v7` branch** with working CI. 8. **Merge `v8` into `main`.** 9. **Triage the open v7 issues and pull requests.** Close everything except v7 bug reports; post a pinned issue explaining the change and use a saved reply linking to it. This deliberately happens at merge time, not earlier — doing it before there's an announcement to point at just generates weeks of confusion. -10. **Publish** under the non-`latest` dist-tag. Verify: `npm install prisma` still yields v7; installing the RC tag yields v8; both binaries work. +10. **Publish** under the non-`latest` dist-tag. Verify: `npm install prisma` still yields v7; installing the RC tag yields v8; the `prisma-next` binary works and no `prisma` binary is declared. 11. **Deprecation notice** on the old `prisma-next` package. 12. **Announce.** diff --git a/projects/prisma-8-rc1/spec.md b/projects/prisma-8-rc1/spec.md index c45cb014e8..e4ebb4b75d 100644 --- a/projects/prisma-8-rc1/spec.md +++ b/projects/prisma-8-rc1/spec.md @@ -56,7 +56,7 @@ New queries are written against the v8 client; old code paths stay on v7. At the # Cross-cutting requirements -1. **Parallel install must actually work, and be proven by a fixture.** One project, both versions installed, one Postgres database, v7 owning DDL. The npm alias covers library resolution; the bin conflict is resolved by v8 shipping both `prisma` and `prisma-next` bins with v7 winning `prisma` during coexistence; migration ownership stays with v7 until a single final cutover (adoption via `contract infer` → `db sign`, per ADR 122). The e2e fixture is simultaneously the coexistence proof, the differential-testing harness, and the executable form of the upgrade guide. +1. **Parallel install must actually work, and be proven by a fixture.** One project, both versions installed, one Postgres database, v7 owning DDL. The npm alias covers library resolution; there is no CLI bin conflict because v8 ships only the `prisma-next` binary (`prisma` unambiguously means v7 until v7 is removed); migration ownership stays with v7 until a single final cutover (adoption via `contract infer` → `db sign`, per ADR 122). The e2e fixture is simultaneously the coexistence proof, the differential-testing harness, and the executable form of the upgrade guide. 2. **Everything that freezes at RC must land before RC.** The freeze set: public package names, error codes, config keys (`extensionPacks` → `extensions`), the `migrations/` directory layout (snapshot centralization), CLI bin names, and the Node/TS/database version floors. Anything not in the freeze set may trail. 3. **Claims in the announcement must have receipts.** "Works" → the supported-surface matrix backed by named green test suites. "TS performance" → the public Bencher project. "Run both in parallel" → the fixture. No unverifiable claims. 4. **The org can see the state at any time.** The Linear project *Prisma 8 RC1* (lead: Will, milestones Jul 18 / Jul 22 / Jul 24 / Jul 31) is the internal dashboard; status updates at each milestone. From e0df5dee13f66247e85bb544bd6853692ea3ed1e Mon Sep 17 00:00:00 2001 From: willbot Date: Thu, 16 Jul 2026 10:26:34 +0200 Subject: [PATCH 7/8] docs(drive): fixture invokes CLIs by unambiguous names, runs per package manager Signed-off-by: willbot Signed-off-by: Will Madden --- projects/prisma-8-rc1/parallel-install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/prisma-8-rc1/parallel-install.md b/projects/prisma-8-rc1/parallel-install.md index 5cb3d2deda..4f435c658f 100644 --- a/projects/prisma-8-rc1/parallel-install.md +++ b/projects/prisma-8-rc1/parallel-install.md @@ -50,7 +50,7 @@ All of the above is assembled from mechanisms that individually exist and are te - v7 runs its migrations, seeds data, and keeps querying through v7 code; - v8 adopts the database, queries the same data, and the results agree; - v7 runs a *further* migration, and the re-adopt routine (infer → review → sign → verify) is exercised; -- both binaries are invoked by their coexistence names throughout. +- the CLIs are invoked by their unambiguous names throughout — `prisma` for v7, `prisma-next` for v8 — and the fixture runs under each supported package manager to prove the alias install and binary resolution behave identically on all of them. This fixture is the receipt for the announcement's migration claim, a regression test forever after, and the skeleton the upgrade guide's code samples are lifted from. **It must be green by July 24** — if it isn't, the announcement's claim gets scaled back to what's actually proven, and that decision is made at the checkpoint rather than discovered by users. From 242917cc425c9380e5fb220d00b4be4d75794c24 Mon Sep 17 00:00:00 2001 From: willbot Date: Fri, 17 Jul 2026 09:59:17 +0200 Subject: [PATCH 8/8] =?UTF-8?q?docs(drive):=20pre-freeze=20item=20?= =?UTF-8?q?=E2=80=94=20remove=20@db.-style=20attributes=20from=20PSL?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Native column types currently ride on v7-style @db. attributes in named-type aliases; PSL syntax freezes at RC, so the removal and its replacement spelling must land before July 31. Signed-off-by: willbot Signed-off-by: Will Madden --- projects/prisma-8-rc1/feature-surface.md | 3 ++- projects/prisma-8-rc1/plan.md | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/projects/prisma-8-rc1/feature-surface.md b/projects/prisma-8-rc1/feature-surface.md index a85e8f72a1..726876a12c 100644 --- a/projects/prisma-8-rc1/feature-surface.md +++ b/projects/prisma-8-rc1/feature-surface.md @@ -25,7 +25,8 @@ Each item here changes a surface that freezes on July 31 (see [release-definitio 3. **Fix the connection-pool crash.** A dropped idle connection currently crashes the host process because no error listener is attached. A production-readiness bug, not housekeeping. 4. **Deduplicate migration contract snapshots.** Every migration folder currently stores full copies of the contract; a chain of N migrations stores roughly 2N copies of N+1 distinct contracts. They move to a single `migrations/snapshots/` folder, one file per distinct contract named by its content hash. Migration folders already record which contracts they go from and to, so they need no new link files. This is safe (a migration's identity hash doesn't cover the snapshots, so nothing invalidates) and must happen now (the folder layout freezes at RC). Files stay plain JSON for reviewability, but the reader also accepts gzipped files from day one so compression stays possible later without another format change. 5. **Sweep everything that embeds the old names.** After the package rename, these all still say `prisma-next` unless someone fixes them: the templates that `init` writes into new user projects (dependency names, commands, comments), the user-facing skills that `init` installs, the documentation links embedded in error messages (which must resolve to real pages at RC), and the published upgrade-instruction skills. The old `prisma-next` npm package needs a deprecation notice pointing at `prisma`. And the names that look internal but freeze — environment variables, the per-user config file path, telemetry identifiers — each need an explicit keep-or-rename decision. -6. **Public API documentation comments.** The exported surface of the per-database packages is what users see on hover in their editor. That set — not all 65 packages — gets an audit pass. +6. **Remove `@db.`-style attributes from PSL.** Today native database column types are expressed through v7-style `@db.` attributes in named-type aliases (`types { Uuid = String @db.Uuid }`) — supported by the parser and printer, emitted by `contract infer`, and used in the example apps. These get deleted from the language before the RC, because PSL syntax freezes then. The work: decide the replacement spelling for native column types, remove the attribute form from parser and printer, update `contract infer` output, regenerate the example contracts and migrations, and record upgrade instructions for existing schemas. +7. **Public API documentation comments.** The exported surface of the per-database packages is what users see on hover in their editor. That set — not all 65 packages — gets an audit pass. ## Quality items that should land before the announcement (but don't freeze) diff --git a/projects/prisma-8-rc1/plan.md b/projects/prisma-8-rc1/plan.md index 1aa3ddbebe..a1d4b19cf7 100644 --- a/projects/prisma-8-rc1/plan.md +++ b/projects/prisma-8-rc1/plan.md @@ -13,6 +13,7 @@ Everything from the topic documents as dated, ordered steps. Deliberately says n - Enumerate the feature-support matrix rows (v8 surface × Prisma 7 capability census) and draft verdicts; produce the list of "works"-claimed cells with no proving test. - Deduplicate migration contract snapshots into `migrations/snapshots/` (the folder layout freezes at RC). - Rename `extensionPacks` → `extensions`, and sweep the config format for other keys we'd regret freezing. +- Remove `@db.`-style attributes from PSL (decide the replacement spelling for native column types first; then parser, printer, `contract infer`, example regeneration, upgrade instructions). PSL syntax freezes at RC. - Fix the connection-pool crash (missing error listeners). - Continue the polymorphism bug-fixing stream (feeds the July 24 call).