From 8ce9b25fad8200cc96f10535bb64a5950cdc50e2 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Sun, 3 May 2026 18:55:07 -0700 Subject: [PATCH] docs(release): document first publish bootstrap --- doc/PUBLISHING.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/doc/PUBLISHING.md b/doc/PUBLISHING.md index 7a4602ad3d0..029144bf297 100644 --- a/doc/PUBLISHING.md +++ b/doc/PUBLISHING.md @@ -190,6 +190,42 @@ When you add a new public package: PR CI now checks changed release-enabled package manifests against npm. That catches a missing first-publish bootstrap before the change reaches `master`. +### One-time bootstrap sequence for a new package + +The first publish of a brand-new package still needs one human maintainer with npm write access. +After that, trusted publishing can take over. + +Example for `@paperclipai/adapter-acpx-local` from the repo root: + +```bash +# expected before bootstrap: npm does not know this package yet +npm view @paperclipai/adapter-acpx-local version + +# build the publish payload +pnpm --filter @paperclipai/adapter-acpx-local build + +# confirm local npm auth +npm whoami + +# preview the exact tarball contents +cd packages/adapters/acpx-local +npm pack --dry-run + +# one-time bootstrap publish +npm publish --access public +``` + +After that first publish succeeds: + +1. open `https://www.npmjs.com/package/@paperclipai/adapter-acpx-local` +2. go to `Settings` → `Trusted publishing` +3. add repository `paperclipai/paperclip` +4. set workflow filename to `release.yml` +5. optionally go to `Settings` → `Publishing access` and enable `Require two-factor authentication and disallow tokens` +6. keep `publishFromCi: true` in [`scripts/release-package-manifest.json`](../scripts/release-package-manifest.json) + +Once those steps are done, future canary and stable publishes for that package are automated through GitHub OIDC. The manual step is only the first package creation on npm. + ## Rollback model Rollback does not unpublish anything.