This document defines how the @docs.plus/extension-* package family is versioned, published, and announced. It is the authoritative reference; the release-extensions skill (.agents/skills/release-extensions/SKILL.md) carries the operational subset and points here.
| Field | Value |
|---|---|
| Doctrine | Strict lockstep, Tiptap-style — every publishable extension shares one major |
| Major tracks | The docs.plus product line (1.x = Etherpad, 2.x = Next.js pad) |
| Current phase | Phase 2 — Lockstep active since 2026-10-13. All packages ship together at one version — see Phase 2 |
| Phase 1 | Complete. All 5 published 2.0.0 as npm latest on 2026-08-11 — see Phase 1 |
| Switch-flip | Trigger D, flipped 2026-10-13 — see Trigger D |
| CI guard | Active — .github/workflows/lockstep-guard.yml; see CI Guard |
| Publish gate | Release when ready — see Release Readiness; stable only, no pre-release dist-tags |
The publishable packages:
@docs.plus/extension-hyperlink@docs.plus/extension-hypermultimedia@docs.plus/extension-indent@docs.plus/extension-inline-code@docs.plus/extension-mermaid@docs.plus/extension-placeholder
@docs.plus/webapp and @docs.plus/hocuspocus consume these via workspace:* and have their own independent version lines. They are not part of the lockstep family.
Tag. The product tag is v<version>, for example v2.1.0. It is not a package tag.
Versions. @docs.plus/webapp and @docs.plus/hocuspocus share the product version. Admin keeps its own version.
Git. Push one tag: git push origin v<version>. Never git push --tags.
Tags sit on main. v2.0.0 and v2.0.1 sit off main's history. Every new product tag must point at a commit on main.
GitHub. The Release body is authored from the CHANGELOG.md [<version>] entry, not
sliced from it. A changelog is a record and an announcement is not, so one document served both jobs
less well. Every claim in the body must trace to that entry or to mounted code. This Release is Latest.
Release body voice, approved on v2.0.1. Open by telling readers whether anything changes for
them — v2.0.1 opened "Nothing changes for you as a writer or a reader." One emoji leads each
section, never sprinkled inside sentences. Lead a bug with its symptom, not its fix: "a crashed
backend was reporting success", not "added an exit code parameter". Keep every number and drop every
implementation detail, because the CHANGELOG holds those and the body links to it. Small
before-and-after tables beat prose for sizes and timings. Close on the most interesting finding rather
than the biggest. Simplified English still applies; warm is not the same as long.
Before tagging, audit changelog coverage. Every app, package and extension folder that changed since
the base commit, the last product release commit, needs an entry in its own changelog.
On v2.0.1 the product changelog was written and apps/hocuspocus.server/CHANGELOG.md was missed,
because both share the product version. List the changed folders with
git diff <base>..HEAD --name-only -- apps packages extensions | cut -d/ -f1,2 | sort -u. Prove which
extensions really changed with
git diff <base>..HEAD --name-only -- 'extensions/*/src/**' — a README-only diff is not a release,
and zero source files means no release:family run is needed. Create the tag last, after every
commit including changelog fixes; if a commit lands later, delete and recreate the unpushed tag so it
points at HEAD. Then git push origin main → git push origin <tag> → gh release create, in that
order, because gh mints its own tag when the remote lacks one and gh release create is not
idempotent — a second run errors instead of updating, so use gh release edit to amend.
Per-package Releases. The five @docs.plus/extension-* GitHub Releases from 2026-08-11 were deleted
on 2026-08-26, so the product Release is the only entry a visitor meets. The five git tags stay, because
they pin the source that built each published npm version, and release:family preflight check 8 reads
them. This supersedes Decision: per-package releases over umbrella
for the Releases page only; per-package tags and npm publishing are unchanged.
npm. The product tag does not publish to npm. The @docs.plus/extension-* packages move only through a family release — see Phase 2.
Deploy. Do not add a (build): commit for the version string. The version string is not shown in the UI. The next ordinary deploy applies it.
Changelogs. The product changelog is CHANGELOG.md. Every app, package and extension keeps its own CHANGELOG.md: apps/<name>/, packages/<name>/ and extensions/extension-<x>/. A change gets an entry in the changelog of each folder it touched, and each entry holds only that folder's part. A change outside those folders, such as in scripts/, .github/ or .agents/, goes in the Internal section of the product changelog. The product changelog also sums up the notable changes for users and self-hosters, and the folder entries keep the detail. The hocuspocus Migration section keeps the deploy order, and the product Migration section points to it. packages/supabase/CHANGELOG.md says what each migration does. A private app or package heads each entry with the docs.plus release that carried it, not with its package.json version. packages/floating-popover and packages/floating-tooltip keep their own [2.0.0] line instead: no docs.plus heading, and [Unreleased] lists every change since [2.0.0].
Strict lockstep. All publishable extensions ship at the same MAJOR.MINOR.PATCH. The rule binds from 2026-10-13, when Phase 2 began. When any one of them needs a release at version X, all of them publish at X. Packages with no behavioral changes ship a no-op release (see No-op releases).
Major tracks the product. The major number aligns with the docs.plus product line, not with each extension's individual API churn. This is the React / Vue / Angular / Tiptap pattern: one platform, one major.
Why lockstep over independent versions. The extensions are pieces of one platform that happens to be open source. Webapp consumes all of them; the platform's identity is a single version, not a tuple of versions. Lockstep eliminates the matrix-compatibility question ("does extension-hyperlink@2.3.0 work with extension-indent@1.4.0?") for every consumer, including webapp itself.
What lockstep is not. It is not a guarantee that every release contains a real change in every package. It is a guarantee that any two extensions at the same version were tested and shipped together.
Goal: get all five extensions to 2.0.0 on npm, each on its own schedule.
Outcome. Phase 1 is complete. All five published 2.0.0 as npm latest on 2026-08-11. On 2026-10-13, before the 2.1.0 family release, all five still served 2.0.0 as latest. The rules below are the record of how the cutover ran.
Starting state. extension-hyperlink, extension-hypermultimedia, and extension-indent already served an older version as latest; for those three, 2.0.0 moved latest forward. extension-inline-code and extension-placeholder had never been published, so 2.0.0 was their first release of any version. The per-package cutover tracker was deleted with the Trigger D switch-flip, because this section now holds the outcome.
Rules during Phase 1:
- Each extension's
package.jsonversionis bumped to2.0.0independently when its breaking changes are ready. - Each ships per the existing per-package runbook in the
release-extensionsskill:bun publish --tag latest --otp <code>→git tag <pkg>@2.0.0→gh release create .... - Each carries its own
[2.0.0]CHANGELOG.mdentry following the CHANGELOG style guide. - Each must have the publishable-package scaffolding before its first
2.0.0ship. See Per-package readiness checklist. - No CI guard enforced version alignment. No PR was blocked for non-aligned versions during cutover. The guard arrived with the switch-flip. See CI Guard.
Order of cutover:
extension-hyperlink@2.0.0— first.- The other four — over coming windows, no fixed schedule, in whatever order maturity allows.
Each of the five shipped with a ## [2.0.0] CHANGELOG entry and a passing readiness checklist.
Honest disclosure. @docs.plus/extension-hyperlink@4.3.0 was published to npm by mistake on 2026-04-19, on a semver line the package never had. npm's unpublish window is 72 hours, so it closed on 2026-04-22: 4.3.0 cannot be removed. It is deprecated with a message that names the replacement (done 2026-08-11): the registry returns "deprecated": "Mispublished by mistake — not a real release. Install 2.x instead.", replacing npm's generic "this package has been deprecated", which told an installer nothing.
This still matters now that 2.0.0 has shipped, because 4.3.0 outranks every other published version by semver. It sits at the top of the registry's version list even though latest points at a 2.x version. Re-running npm deprecate overwrites the message, which is how it was set — repeat this if the wording ever needs to change:
npm deprecate '@docs.plus/extension-hyperlink@4.3.0' 'Mispublished by mistake — not a real release. Install 2.x instead.'Verify with npm view '@docs.plus/extension-hyperlink@4.3.0' deprecated. npm deprecate is a registry operation, not package management, so the Bun-only rule does not apply. It is a write, so npm 2FA may ask for --otp. Run it from the maintainer laptop with the npm login used to publish.
The [2.0.0] CHANGELOG entry is the consumer-facing disclosure and must state the same outcome. Future cutover entries follow the same honesty norm.
Lockstep is not auto-derived. It activates the moment both of the following hold:
- Family alignment: all five publishable extensions are at the same major version on npm (i.e. all five have shipped a
2.x). - Deliberate switch-flip: an explicit commit lands on
mainthat updates this section ofRELEASE_POLICY.mdfrom "Phase 1 — Cutover" to "Phase 2 — Lockstep active". The same commit adds the CI guard described in CI Guard.
The deliberate-commit gate is intentional. Family alignment alone is not enough — the maintainer must affirm that the family is ready for coordinated releases. This prevents lockstep from accidentally engaging the moment the fifth 2.0.0 lands while the team is still treating it as a per-package release.
Status: both conditions hold. All five reached 2.0.0 on npm on 2026-08-11. The switch-flip commit is dated 2026-10-13. It carries the CI guard and comes ahead of the 2.1.0 family release. Lockstep is now binding.
Goal: ship coordinated minor and patch releases of the family with one script invocation.
Active since 2026-10-13. The first family release is 2.1.0, alongside product v2.1.0.
The script orchestrates the per-package OTP rhythm and batches the post-publish work. It is implemented as the Bun script scripts/release-family.ts and wired as the root script release:family; the sections below describe what it does today.
It reads the package list from scripts/publishable-extensions.ts — the same SSOT the test gates use — and takes the target version from the packages themselves. Flags: --dry-run (run every check, print the plan, never publish or tag), --allow-noop, --generate-noop-changelogs, --help. There is no dist-tag flag; every publish goes to latest (see Release Readiness).
Every check runs before any prompt. Failures are collected and reported together, not one per run:
- Lockstep: every publishable package's
package.jsoncarries the sameversion. That version is the target. - CHANGELOG entry: each package's
CHANGELOG.mdcontains a## [<target-version>]heading. - Build freshness: each package has a non-empty
dist/, and no file undersrc/is newer than the newest file underdist/. The script never builds — a staledist/is an error to fix, not something it repairs. - Per-package preflight: each package's
prepublishOnlyisbunx release-preflight(delegated to@docs.plus/release-tooling) and passes. It assertsbun/*user-agent, nocatalog:leaks in built bundles, and dist artifacts derived from the consumer'sexportsmap all present. - Git state: working tree is clean; HEAD matches
origin/main. - Identity:
npm whoamireturns a user;git config user.emailis set. - Tag collision: none of the planned tags
<pkg>@<target-version>already exist locally or on the remote. One exception keeps a resumed run from failing on its own tags. A local tag that points atHEADand whose version is already on npm was written by the previous run. The script accepts that tag. Both conditions must hold, or a genuine re-release would be masked. A tag on the remote is always an error. The script pushes tags only after the whole publish loop, so a mid-loop failure never leaves one there. - No-op intentionality: the previous version is the last entry of
npm view <pkg> versionsother than the target, andgit diff '<pkg>@<prev>'..HEAD -- extensions/<pkg>/src/decides. An empty diff marks a no-op and requires an explicit--allow-noopflag. A package with no published versions, or with no local git tag for its previous version, is skipped by this check. (No-op releases are expected — see No-op releases — but should be intentional.)
If anything fails, no OTP is requested and the script exits non-zero.
Packages run in the order declared by scripts/publishable-extensions.ts; there are no inter-extension deps to topologically order today. Before the loop, the script prints the target and asks for a y/N confirmation. --dry-run skips that confirmation, and stops short of every publish, tag, and push.
For each package:
- Call
npm view <pkg>@<target-version>to detect "already published" (the resume case after a mid-stream failure). If already published, skip the publish and create the local tag if it is missing. - Prompt for OTP. Input must be 6–8 digits.
- Run
bun publish --tag latest --otp <code>. - Run
git tag '<pkg>@<target-version>'.
On bun publish failure: halt immediately, do not retry (would burn an OTP), print Resume with: bun run release:family. Already-published packages stay published — npm has no transactional multi-publish.
git push origin <tag> <tag> …— one call with the explicit tag list. Nevergit push --tags(AGENTS.md §Release Safety).- Print summary: target version, published count, skipped count, and one npm URL per package.
The script creates no per-package GitHub Release. The product Release announces the family and names each extension version, so discord-release.yml posts once. See Per-package Releases and Decision: per-package releases over umbrella.
- Patch (
2.1.3): any package needs a bug fix → every package ships2.1.3. - Minor (
2.2.0): any package adds a re-exported symbol or any other backward-compatible feature → every package ships2.2.0. - Major (
3.0.0): any package introduces a breaking change, or the docs.plus product line itself bumps to a new major → every package ships3.0.0.
The product-line major bump is the strongest case: webapp@3.0.0 ships → all extensions go to 3.0.0 regardless of whether their own APIs changed.
When a package has no behavioral changes since its previous release but ships in a coordinated family release anyway, it gets an auto-generated CHANGELOG entry:
## [<version>] — <date>
Aligned to docs.plus <version> family release. No behavioral changes since <prev-version>.bun run release:family --generate-noop-changelogs writes this entry verbatim for every package the no-op detection finds (git diff <prev-tag>..HEAD -- extensions/<pkg>/src/ empty) and then exits without publishing. The maintainer reviews and commits the generated entries, then re-runs the script; preflight check #2 verifies they exist. The flag refuses to run while lockstep is violated, since the target version would be ambiguous.
Set by the extension-hyperlink@2.0.0 rewrite. Applies to every publishable extension.
Voice: entry prose follows Simplified English. The section headings below are exempt from it. A published entry is frozen against fact changes: its facts, versions, dates, headings, and ordering never change. Only a maintainer-approved prose pass may reshape its sentences.
Format: keepachangelog.com.
Per-release section ordering, omit empty subsections:
## [X.Y.Z] — YYYY-MM-DD
### Highlights (mandatory for major/minor; optional for patch)
### Breaking / Breaking Changes (presence implies a Migration section)
Published entries use the shorthand `### Breaking` (same meaning as `Breaking Changes`). New entries may use either heading; do not rename shipped headings for style-only churn.
### Added
### Changed
### Fixed
### Security
### Removed
### Documentation
### InternalHighlights bullet style: 3–6 bullets, each a complete sentence, each calling out a user-facing capability with a concrete name (normalizeHref, SpecialUrlType, etc.). The extension-hyperlink@2.0.0 Highlights block is the template.
Migration section: required if and only if there's a Breaking Change. Inside it: a one-shot rename script for the mechanical changes (where applicable), plus before/after code diffs for each break.
Honest disclosure: disclose mispublishes, unpublishes, deprecations, and version-line resets in the CHANGELOG. Put each one in the entry where it happened. Use a "Pre-X.0 development history" appendix instead when public versions diverged from internal milestones. That appendix is a one-time artifact, not a recurring section.
Never auto-generate from commit subjects. Lerna, Changesets, and Release-Please all default to "extract fix: / feat: lines from commit messages and stitch them together". This produces low-quality changelogs that undercut the editorial bar set by extension-hyperlink@2.0.0. The manual editorial process is the policy. None of those tools are adopted.
Release when ready. There is no pre-release dist-tag, no soak window, and no promotion step. Every publish goes to the default latest tag. It happens when the maintainer decides the package (Phase 1) or the family (Phase 2) is ready. Ready typically means the change set is complete, the readiness checklist and preflight pass, and the CHANGELOG entry is written. Bump the version, publish, done.
Why this is safe without a soak. The webapp consumes the extensions via workspace:*. So every change ships to docs.plus production from source well before it is ever published to npm. Production exposure precedes the registry, not the reverse. The quality gates are the per-package test suites, release-preflight, and the readiness checklist below, not a waiting period.
If third-party consumption at scale ever demands staged rollouts, revisit this section then — that would be the moment a pre-release channel justifies its cost.
Discord announcements. discord-release.yml fires once, for the product Release. The family has no per-package GitHub Releases (ruled 2026-08-26, applied to the release script on 2026-10-13).
The guard is implemented. The Trigger D switch-flip added it on 2026-10-13. The spec below is the contract the workflow satisfies.
Location: .github/workflows/lockstep-guard.yml.
Trigger: any PR that touches extensions/extension-*/package.json.
Check: parse the version field of every package listed in scripts/publishable-extensions.ts, the same list release:family reads. If they are not all identical, the PR fails with a clear message:
Lockstep violated: extension-X is at 2.1.0 but extension-Y is at 2.0.3.
All publishable extensions must share a version.
See RELEASE_POLICY.md "Versioning Doctrine".
Bypass: add the label lockstep-bypass to the PR. The job then shows as skipped. Adding or removing the label runs the workflow again. Reserved for the rare hotfix that legitimately ships outside the family — should be near-zero in practice.
Activation: the workflow is active from the Trigger D commit. Its only condition is the bypass label; there is no dormant if: false state. No retroactive enforcement, no PR breakage during cutover.
Before any extension first publishes, it needs the publishable-package scaffolding. The checklist applies to every package, including the three that already have older versions on npm. An existing npm listing is not evidence that the current scaffolding is in place:
-
LICENSEin.gitignore(rootLICENSEis the single source of truth;prepackregenerates it before each pack) -
"@docs.plus/release-tooling": "workspace:*"indevDependencies -
"prepack": "bunx release-prepack"inpackage.json(copies rootLICENSEinto the package via the shared bin) -
"prepublishOnly": "bunx release-preflight"inpackage.json(assertsbun/*user-agent, nocatalog:leaks, dist artifacts present — derived from the consumer'sexportsmap) -
publishConfig.access: "public"inpackage.json -
exports.require.typespoints to./dist/index.d.cts(not.d.ts) -
sideEffects: ['**/*.css'](not barefalse) if the package ships any CSS -
homepage,bugs, and discovery-orientedkeywordspopulated inpackage.json - A CHANGELOG.md entry for the first version it publishes, following the style guide
- Release-gate tests passing — hyperlink:
bun test src+ Cypress; indent: Jest + Cypress; hypermultimedia / inline-code / mermaid / placeholder: clean-room Cypress againstdist/ -
bun pm packdry-run produces a clean tarball
The extension-hyperlink package is the reference shape — when wiring a new extension, copy from there. Never copy the prepack / preflight script bodies into per-package scripts/ directories; the canonical implementation lives in @docs.plus/release-tooling and is consumed via the bin commands above. Same DRY principle as @docs.plus/eslint-config, tsconfig.base.json, and tsup.base.ts.
These are the explicit decisions made during the policy design session. Each is locked in; revisiting requires updating this document.
The per-package tags collectively pin the source state (lockstep means they all point to the same commit). An additional docs.plus-family@<version> umbrella tag would be redundant. It would add one more tag-management thing to think about, and no existing infrastructure would consume it. Skipped.
The Discord workflow fired per release.{published,prereleased} event with package-specific embeds (color-coded by stability, install hint per package). A family release posted one Discord embed per package in ~30 seconds. Inventing an umbrella-release format would have meant rewriting the Discord workflow and losing per-package install hints. For a few-times-per-year event, one minute of Discord noise was fine. Per-package releases were retained.
Superseded on 2026-08-26. The per-package Releases were deleted, and the product Release is the only one. On 2026-10-13 the maintainer applied that to scripts/release-family.ts: it pushes the tags and creates no GitHub Release.
No-op CHANGELOG entries are pure boilerplate (one fixed sentence). Auto-generating them removes the typing burden per family release and removes the "I forgot to write the no-op entry" failure mode. The script generates them; the maintainer commits them before publish; preflight check #2 verifies they exist. Adopted.
Supersedes the earlier "webapp-gated soak" decision. @next was retired before anything was ever published to it. The webapp already soaks every change from workspace:* source in production. A registry-side pre-release channel therefore added process without adding signal. Publishes go straight to latest when the maintainer decides they are ready; GitHub releases are never marked pre-release. See Release Readiness.
Lerna, Changesets, and Release-Please all default to commit-message-driven changelog generation, which undercuts the editorial bar this policy demands. Manual changelog authorship is the policy. The bun run release:family script orchestrates the OTP rhythm and batches post-publish work; it does not author content.