Releasing math editor

See Editing scenarios for stable scenario IDs, acceptance criteria, coverage gaps and per-run reporting.

The source stays in this monorepo. The local batch release includes @barocss/math-editor, nine public rich-text plugins and four text packages (math-editor-text, math-editor-codemirror6, math-editor-codemirror5, math-editor-monaco, all under @barocss). All use MIT, public npm access and the latest tag. Framework adapters are core subpaths and share the core version. The private integration workspace and other products are excluded.

Versions remain independent; a batch release does not force every package to change. VS Code is a separate VSIX/Marketplace release and is not published by this npm command.

Local release

# Repository root. Login is handled by npm, never by storing credentials in the repository.
npm login --registry=https://registry.npmjs.org/
# After reviewing versions, changelogs and browser validation:
pnpm release:math

This one command runs core formatting/type/unit checks, integration type/unit checks, builds, package validation and release-tool tests. It verifies the core entry points and each plugin's packed declarations, runtime imports and required files. It then runs one pnpm -r publish command for the fourteen allowed names. pnpm release is an alias for this workflow.

Only the inspected package contents enter a generated workspace under output/math-batch-releases/release-*/. Wrapper manifests use publishConfig.directory to point at those contents. They give pnpm an explicit core-first dependency order without adding dependencies to the published plugin manifests. Publish lifecycle scripts are disabled because validation and builds already ran. Git checks are disabled only for this generated workspace.

pnpm checks npm and skips package versions that already exist. It packs the inspected contents again, so the final archive checksum can differ from the preparation archive. The batch is not an atomic registry transaction. npm may still request authentication for individual packages; one command does not guarantee one authentication prompt.

For checks without publishing:

# Build and inspect all fourteen packages. No registry publication.
pnpm release:math:prepare
# Also exercise recursive publishing with npm's dry-run flag.
# This can read registry metadata; it does not upload packages.
pnpm release:math:dry-run

release.json records the candidate versions, artifact hashes and command status. On success, pnpm-publish-summary.json lists newly published packages; versions skipped by pnpm are absent. A dry-run summary is not evidence of publication. If publishing fails, preserve the report and check each candidate version on npm. pnpm 8 may not write its summary after a partial failure. Resolve any uncertain results before running the batch again; never use --force to retry.

Before releasing UI changes, also run pnpm --filter @barocss/math-demo test:e2e and the demo build. Verify the intended package name/version and changelog. A version already published to npm must never be reused. The repository's release workflow is manual validation only; it does not publish on main pushes.

Subsequent versions

Run pnpm changeset, select the affected math core and/or public plugins, and write a user-facing change summary.
Use patch for compatible fixes and minor for features. During 0.x development, clearly identify breaking API changes in a minor release. Reserve 1.0.0 for the agreed stable API.
Run pnpm version:math:plan to preview the core, nine rich-text plugin and four text-package versions. Run pnpm version:math to apply that plan. Changesets runs in a temporary math-only workspace and copies back only affected math manifests/changelogs. Unrelated product changesets remain untouched. Review plugin peer-range changes before publishing.
Review and commit the version/changelog and any dependency/lockfile changes with the implementation. Run release validation, then publish locally.
Record package-specific Git tags on the release commit, and update the site with the matching package version. The batch command does not create commits or tags.

The scoped Changesets configuration only promotes peer dependents when the new version leaves their supported range. Widen a compatible peer range explicitly and add a patch changeset; incompatible range changes still require release review.

Text tarballs are installed with the packed core into a temporary consumer using npm install --offline --ignore-scripts --legacy-peer-deps. Host SDKs come from the local installation. Strict public declaration checks and runtime import checks run there. This validates package contents and local installation, not npm availability or a fresh registry peer installation. Monaco interaction is covered by browser QA. See text editor validation for native IME and physical mobile checks that remain open.

Versioning is separate from publishing. Repeating a publish command must not create another version. Avoid pnpm version-packages and unfiltered pnpm -r publish for a math-only release because they can include other products.

The host release guide lists the nine plugins and explains changes to shared implementation. For an explicit core-only release, use pnpm version:math:core, pnpm release:math:core:prepare and pnpm release:math:core.

Website

apps/math-demo remains the site source. The static deployment repository is barocss/math-editor-site, with GitHub Pages at math-editor.barocss.com. Build the site directly from workspace source:

pnpm build:math:site

This builds the main site and the nine-plugin integration sample without a core tarball, package dist build, npm login, registry lookup or publication check. Workspace package exports resolve local source, including the private common module. No package version bump is required to rebuild or deploy the site. release.json records source: "workspace-source" and the local package versions as metadata; those versions do not claim that the packages are published.

For an explicit package-artifact check, the previous command remains available:

pnpm release:math:site /path/to/barocss-math-editor.tgz

Both commands print the prepared static site directory and do not deploy it. Website deployment and npm publication are independent operations.