Skip to main content

Alpha Publishing

Jess uses a guided alpha release flow so publishing is predictable, repeatable, and low-stress.

Publish scope​

The current alpha publish set is controlled by:

  • scripts/release/alpha-allowlist.json

The publish set includes the direct parser/plugin closure installed by jess: Jess, Less, and SCSS parser plugins plus their parser packages. CSS is available only when a consumer explicitly configures a CSS document plugin; Jess does not install or route .css entries by default. @jesscss/css-parser remains in the set because the shipped dialect grammars use its shared CSS grammar. The set also includes @jesscss/compiler, which owns the shared render pipeline used by the root jess package and the Less plugin stack. Packages with private runtime dependencies remain intentionally excluded.

Branch/tag guardrails​

  • alpha npm tag publishes are only allowed from branch alpha.
  • non-alpha npm tags (future stable releases) are only allowed from branch main.
  • These rules are enforced in the publish script, not just in docs.

Cut the release snapshot​

An alpha is a release snapshot, not a normal branch integration. After the exact pushed origin/dev candidate has passed its intended gates, snapshot it onto an up-to-date alpha worktree, add the owner-reviewed user-facing release notes, and commit that snapshot. Do not ordinary-merge or rebase dev into alpha. The full cut procedure is in the repository docs/process/releasing-alpha.md.

Friendly one-command flow​

From repo root:

pnpm run release:alpha:dry-run

If dry-run is healthy and you are on branch alpha:

pnpm run release:alpha

What the orchestrator does​

release:alpha runs:

  1. Branch + working tree safety checks
  2. Baseline verification and publish-set validation
  3. Registry-aware lockstep alpha versioning
  4. Release commit + annotated git tag
  5. Push branch and tag
  6. Publish allowlisted packages to npm tag alpha
  7. npm smoke checks for @alpha installs

Before the publish dry-run it also packs the allowlisted release set and installs those tarballs into an empty npm consumer. That proof imports every package by both ESM and CommonJS, exercises the packed jess CLI, and verifies the optional JS-plugin sandbox gate without workspace links. The Less package owns the separate lessc compatibility command and verifies it through its own packed-consumer proof. The jess command can use familiar file and stream ergonomics without becoming a lessc alias.

Manual commands (advanced)​

  • Preflight gate only:
pnpm run release:alpha:check
  • Version only:
pnpm run release:alpha:version
  • Publish only:
pnpm run release:alpha:publish

CI backup path​

If you want Actions to publish instead of local CLI, run:

  • Workflow: .github/workflows/publish-alpha.yml
  • Trigger: manual workflow_dispatch only

The recommended default remains pnpm run release:alpha from CLI.

Recovery strategy​

  • If one package fails during publish, fix root cause and rerun release:alpha:publish.
  • Avoid unpublish unless absolutely necessary and allowed by npm policy.
  • Prefer releasing a new -alpha.N+1 with fixes.