Skip to content

Correct package-first release order - #25

Merged
raghubetina merged 1 commit into
mainfrom
codex/fix-plugin-release-order-20260807
Aug 7, 2026
Merged

Correct package-first release order#25
raghubetina merged 1 commit into
mainfrom
codex/fix-plugin-release-order-20260807

Conversation

@raghubetina

Copy link
Copy Markdown
Contributor

Summary

  • publish and reconcile plugin 0.1.0 under next before opening the API 0.2 maintenance window, while latest, the public alpha.3 catalog, and staging remain unchanged
  • document and pin the isolated no-service direct-package check, including fail-closed handling, public registry provenance, canonical validation, retained evidence, and exact plugin/CLI assertions
  • serialize web then worker activation, bounded qualification, catalog promotion, fresh public verification, existing-install handling, and rollback

Verification

  • npm run check (61 tests)
  • npm audit
  • exact CLI contract and deterministic plugin package checks
  • prospective registry/tag/catalog release-order check
  • Skill validation and gh skill publish --dry-run
  • hardened direct-package rehearsal against public plugin alpha.3 and bundled CLI alpha.2
  • deliberate missing-package rehearsal proving nonzero fail-closed behavior

Boundaries

This change does not tag, publish, promote the catalog, deploy, or call First Draft. Package, runtime, compatibility, and tarball bytes are unchanged.

Publish and reconcile the compatible plugin before opening the API
0.2 maintenance window so a package failure cannot strand staging on an
incompatible contract.

Document the isolated direct-package proof, serialized web and worker
activation, catalog promotion, rollback, and existing-client boundaries.
Pin those constraints in release contract tests.
@raghubetina
raghubetina merged commit b3e53a2 into main Aug 7, 2026
2 checks passed
@raghubetina

Copy link
Copy Markdown
Contributor Author

Post-merge retrospective. This is the PR that turned release order into policy: publish and reconcile the
exact package under next before opening the API 0.2 maintenance window, while latest, the public alpha.3
catalog, and staging stay untouched. The isolated no-service direct-package check it documents and pins
(fail-closed handling, public registry provenance, canonical validation, retained evidence) became the
standing verification step every later promotion cites. Reviewed today, the interesting property is how much
of the eventual RELEASING.md policy (#33, #41) is this PR's ordering rules restated; the correction stuck.
Nothing to flag retrospectively.

@raghubetina

Copy link
Copy Markdown
Contributor Author

"Package-first" sounds like trivia until you see what it protects during a breaking API transition.

The setup: a new package version and a service API change need to ship together. The wrong order is service
first: the moment the service moves, every existing install is broken until the new package appears, and your
maintenance window is a race. The order this PR fixes into policy: publish the new package under next
(installable but not default), verify it against the registry in isolation, and only then open the
maintenance window for the service, keeping latest and the public catalog pinned to the old, working pair
throughout. Existing users stay on a coherent old-package-plus-old-API world; the transition happens in a
staging lane (next) where breakage affects only people who opted in.

The other keeper is the isolated direct-package check: install the exact published tarball from the public
registry on a machine with no service access and no repository checkout, and verify it fails closed (clear
errors, no half-working state) when it cannot reach what it needs. Products get judged by strangers on clean
machines; verifying from inside your own development environment proves almost nothing about that first
impression.

Dist-tags are the whole mechanism here: next and latest are just named pointers into the same immutable
version set, which is what lets "published" and "default" be different events days apart.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant