From 0c48af987ea33c36525a5260d81949dc88cae4ea Mon Sep 17 00:00:00 2001 From: willbot Date: Mon, 17 Aug 2026 19:34:21 +0200 Subject: [PATCH 1/3] Brief: the `dev` dist-tag must never fall behind `latest` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A release publish moves the release tag and leaves `dev` on the last routine push, so `dev` names an older version than `latest` until someone pushes again. prisma-cli reads the products' `dev` tags to build its dev channel, so while that lasts every dev CLI regresses to older product code than the released CLI carries — silently, since a dev build depending on dev builds breaks no rule. Operator ruling 2026-08-17: fix it in the products' publish strategies rather than working around it here by comparing versions. This repo has the same defect and fixes it the same way, in a follow-up. Signed-off-by: willbot Signed-off-by: Will Madden --- .../assets/briefs/dev-tag-parity-handover.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 .drive/projects/prisma-cli-v8/assets/briefs/dev-tag-parity-handover.md diff --git a/.drive/projects/prisma-cli-v8/assets/briefs/dev-tag-parity-handover.md b/.drive/projects/prisma-cli-v8/assets/briefs/dev-tag-parity-handover.md new file mode 100644 index 00000000..1ea3280a --- /dev/null +++ b/.drive/projects/prisma-cli-v8/assets/briefs/dev-tag-parity-handover.md @@ -0,0 +1,51 @@ +# Handover brief — the `dev` dist-tag must never fall behind `latest` + +For the agents working in `prisma/composer` and `prisma/prisma`. Small, self-contained, one step in each publish workflow. + +## The defect + +A release publish moves `latest` (or `next`) and leaves the `dev` tag where the last routine push to `main` put it. So immediately after a release, `dev` points at an **older** version than `latest`: + +``` +$ npm view @prisma/composer-cli dist-tags +{ latest: '0.7.0', dev: '0.6.0-dev.23' } # dev is older than latest +``` + +That is wrong on its own terms: `dev` means "the newest build from `main`", and a release commit is a build of `main`. It stays wrong until someone happens to push another commit. + +`prisma/prisma-cli` has the same defect in its own workflow (`dev` at `8.0.0-rc.2-dev.51` while `next` is at `8.0.0-rc.3`) and is fixing it the same way. + +## Why it matters to us specifically + +`prisma/prisma-cli` follows your `dev` tags to build the CLI's dev channel: a dev build of the CLI depends on your latest dev builds, and a release of the CLI depends on your releases (operator ruling 2026-08-17; `docs/oss/release-automation.md` in prisma-cli). We read the tag and trust it. + +So while your `dev` tag lags, every dev build of the CLI **regresses** to an older version of your product than the released CLI carries. It does not fail any check — a dev build depending on dev builds is exactly what that channel is for — it just quietly tests older code than the release does, which is the opposite of what a dev channel is for. + +We are deliberately not working around it in prisma-cli by comparing versions and picking the newer tag. The tag should be right. + +## The fix + +After a release publish succeeds, point `dev` at the released version: + +```bash +npm dist-tag add "@" dev +``` + +For every package the release publishes, at the version each one actually shipped — packages excluded from your lockstep ship at their own version, so do not assume one version string covers them all. + +Placement: after the publish step and after whatever creates the GitHub Release, keyed on the publish having succeeded. If the release publish did not happen, the tag must not move. + +## Two things to check while implementing + +1. **Whether your publish credentials can write a dist-tag.** If the workflow publishes over npm OIDC trusted publishing, the short-lived token is issued for publishing; confirm it also authorises `PUT /-/package/{pkg}/dist-tags/{tag}` before relying on it. If it does not, the alternative is a granular token with write access to those packages, and that is worth knowing rather than discovering during a release. +2. **Idempotence on a rerun.** `npm dist-tag add` on a tag that already points at that version is a no-op and should not fail the run. A rerun of a release publish is a normal event. + +## How to know it worked + +After the next release, for every published package: + +```bash +npm view dist-tags +``` + +`dev` and the release tag should name the same version, and `dev` should never name an older one. Worth asserting in the workflow rather than checking by eye. From 8e955bc0fe4002a57d5dc1c9a4ffa4e32ba3da79 Mon Sep 17 00:00:00 2001 From: willbot Date: Tue, 18 Aug 2026 07:58:02 +0200 Subject: [PATCH 2/3] Correct the brief: OIDC cannot move a dist-tag npm's docs are explicit that OIDC authentication supports `npm publish` and `npm stage publish` only; other commands still need traditional authentication, and a dist-tag write is one of them. The brief prescribed `npm dist-tag add`, which would have sent both product repos into the same wall. The fix is what the operator said in the first place: publish a dev build for every main build, including the release commit. It needs no new credential because it goes through the publish path that already works. Signed-off-by: willbot Signed-off-by: Will Madden --- .../assets/briefs/dev-tag-parity-handover.md | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/.drive/projects/prisma-cli-v8/assets/briefs/dev-tag-parity-handover.md b/.drive/projects/prisma-cli-v8/assets/briefs/dev-tag-parity-handover.md index 1ea3280a..69270cfc 100644 --- a/.drive/projects/prisma-cli-v8/assets/briefs/dev-tag-parity-handover.md +++ b/.drive/projects/prisma-cli-v8/assets/briefs/dev-tag-parity-handover.md @@ -25,20 +25,13 @@ We are deliberately not working around it in prisma-cli by comparing versions an ## The fix -After a release publish succeeds, point `dev` at the released version: +Publish a dev build of the release commit too. A release commit is a build of `main`, so it gets a dev version like any other build of `main`: after the release publish succeeds, publish the same tree again as `-dev.` under the `dev` tag. -```bash -npm dist-tag add "@" dev -``` - -For every package the release publishes, at the version each one actually shipped — packages excluded from your lockstep ship at their own version, so do not assume one version string covers them all. - -Placement: after the publish step and after whatever creates the GitHub Release, keyed on the publish having succeeded. If the release publish did not happen, the tag must not move. +**Do not try to move the tag with `npm dist-tag add`.** If you publish over npm OIDC trusted publishing, that will not work: npm's documentation states that OIDC authentication supports `npm publish` and `npm stage publish` only, and that other commands still require traditional authentication. A dist-tag change is one of those. Reaching for a long-lived npm token to work around it would give up the property that makes trusted publishing worth having — that no credential exists which could publish out-of-band if leaked. Publishing a second version needs no new credential, because it goes through the same `npm publish` path that already works. -## Two things to check while implementing +The version this produces sorts above the release under semver (`8.0.0-rc.4-dev.55` > `8.0.0-rc.4`), which is correct: it is a later build of the same code. -1. **Whether your publish credentials can write a dist-tag.** If the workflow publishes over npm OIDC trusted publishing, the short-lived token is issued for publishing; confirm it also authorises `PUT /-/package/{pkg}/dist-tags/{tag}` before relying on it. If it does not, the alternative is a granular token with write access to those packages, and that is worth knowing rather than discovering during a release. -2. **Idempotence on a rerun.** `npm dist-tag add` on a tag that already points at that version is a no-op and should not fail the run. A rerun of a release publish is a normal event. +The cost is one extra published version per release. That is the price of the `dev` tag meaning what it says. ## How to know it worked From 006f2f2741479e7750882bf11119fd2f191f69ae Mon Sep 17 00:00:00 2001 From: willbot Date: Tue, 18 Aug 2026 09:21:39 +0200 Subject: [PATCH 3/3] Address review on the dev-tag brief Language identifier on the output fence; the publish command spelled out with its --tag dev, since omitting it publishes to latest; and the expected dist-tag pair given explicitly, with the semver ordering that makes the dev version sort above the release. Signed-off-by: willbot Signed-off-by: Will Madden --- .../assets/briefs/dev-tag-parity-handover.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/.drive/projects/prisma-cli-v8/assets/briefs/dev-tag-parity-handover.md b/.drive/projects/prisma-cli-v8/assets/briefs/dev-tag-parity-handover.md index 69270cfc..63b21924 100644 --- a/.drive/projects/prisma-cli-v8/assets/briefs/dev-tag-parity-handover.md +++ b/.drive/projects/prisma-cli-v8/assets/briefs/dev-tag-parity-handover.md @@ -6,7 +6,7 @@ For the agents working in `prisma/composer` and `prisma/prisma`. Small, self-con A release publish moves `latest` (or `next`) and leaves the `dev` tag where the last routine push to `main` put it. So immediately after a release, `dev` points at an **older** version than `latest`: -``` +```console $ npm view @prisma/composer-cli dist-tags { latest: '0.7.0', dev: '0.6.0-dev.23' } # dev is older than latest ``` @@ -25,7 +25,13 @@ We are deliberately not working around it in prisma-cli by comparing versions an ## The fix -Publish a dev build of the release commit too. A release commit is a build of `main`, so it gets a dev version like any other build of `main`: after the release publish succeeds, publish the same tree again as `-dev.` under the `dev` tag. +Publish a dev build of the release commit too. A release commit is a build of `main`, so it gets a dev version like any other build of `main`: after the release publish succeeds, publish the same tree again as `-dev.`, explicitly tagged: + +```bash +npm publish --tag dev +``` + +The tag is not optional. Without it npm publishes to `latest`, which would put a dev build in front of every consumer. **Do not try to move the tag with `npm dist-tag add`.** If you publish over npm OIDC trusted publishing, that will not work: npm's documentation states that OIDC authentication supports `npm publish` and `npm stage publish` only, and that other commands still require traditional authentication. A dist-tag change is one of those. Reaching for a long-lived npm token to work around it would give up the property that makes trusted publishing worth having — that no credential exists which could publish out-of-band if leaked. Publishing a second version needs no new credential, because it goes through the same `npm publish` path that already works. @@ -41,4 +47,10 @@ After the next release, for every published package: npm view dist-tags ``` -`dev` and the release tag should name the same version, and `dev` should never name an older one. Worth asserting in the workflow rather than checking by eye. +`dev` should name the dev build of the release commit, and never an older version than the release tag. Assert it in the workflow rather than checking by eye — the failure is silent otherwise: + +```bash +npm view dist-tags --json +``` + +The pair to expect after releasing `8.0.0-rc.4` is `latest: 8.0.0-rc.4` (or `next:`, per your convention) and `dev: 8.0.0-rc.4-dev.`. Note that the dev version sorts *above* the release under semver, because a longer pre-release with an alphanumeric identifier ranks higher: `8.0.0-rc.4` < `8.0.0-rc.4-dev.55`. That is the ordering you want, and it is worth checking your assertion agrees with it rather than assuming string comparison does the right thing.