stack/docs/design/prerelease-next-dist-tag-pipeline.md

npm @next prerelease lane

Status: IMPLEMENTED

Current behavior

tools/install.sh --next provides the prerelease integration lane for the permanent next branch.

The lane is fast-by-default:

1. Install framework files from the next source archive.

2. Resolve the Gitea npm registry next dist-tag for the globally installed packages:

   npm view @mosaicstack/gateway@next version
   npm view @mosaicstack/mosaic@next version
   

3. Require both resolved versions to share the same next.<pipeline> suffix, then install the exact resolved versions.

4. If either @next package is missing, unreachable, mismatched, or fails to install, fall back to the source-build path at next.

--next never hard-fails solely because the prerelease npm dist-tag is unavailable.

Published packages

The next publish pipeline publishes non-private @mosaicstack/* packages to the Mosaic Gitea npm registry:

https://git.mosaicstack.dev/api/packages/mosaicstack/npm/

Observed next dist-tags after enabling the pipeline:

@mosaicstack/mosaic@next  -> 0.0.49-next.1633
@mosaicstack/gateway@next -> 0.0.7-next.1633

The gateway also publishes a Docker image as gateway:sha-<short> on next merges. The installer fast path uses the npm gateway package when available; the Docker image is for deployed gateway/runtime harness flows.

Explicit source lanes

Source builds remain available and are still the authority for explicit ref validation:

• --dev always builds from source.
• --ref <ref> / MOSAIC_REF=<ref> wins over --next and uses the source path for that exact ref.

Pipeline shape

1. Trigger on next merges.
2. Compute the next prerelease version from the upcoming stable version plus the Woodpecker pipeline number (<target-stable>-next.<CI_PIPELINE_NUMBER>).
3. Build and publish non-private packages in CI.
4. Publish to the Mosaic Gitea npm registry with dist-tag next.
5. Keep latest untouched; only main/release promotion can update latest.
6. Publish gateway Docker images from next as gateway:sha-<short> only.

Guardrails

• @next is mutable prerelease convenience, not a deployment pin.
• Stable installs continue to use @latest.
• Contributor validation remains available through --dev --ref <branch>.
• Pipeline output traces every prerelease package back to the source commit on next.
• The installer falls back to source rather than hard-failing on prerelease registry issues.