mosaicstack/stack
16
0
Fork 1
Code Issues 330 Pull Requests 12 Actions Packages Projects Releases 15 Wiki Activity

docs(readme): document both stable and "next" (pre-release) install paths #805

New Issue
Open
opened 2026-07-16 21:29:21 +00:00 by jason.woltje · 0 comments
jason.woltje commented 2026-07-16 21:29:21 +00:00
Owner
Copy Link
Copy Source

Summary

The Mosaic Stack README.md should document install instructions for two distinct channels: the stable release and the "next" (pre-release / bleeding-edge) build — two clear install paths, not just the current single path.

Requested by Jason (Discord 2026-07-16 21:26Z), tracked by Mos (orchestrator).

Current state (as of main @ 59f5f51f)

  • @mosaicstack/mosaic (the installable CLI) publishes to the Gitea npm registry via .woodpecker/publish.yml.
  • The publish step runs pnpm ... publish with no --tag, so both every main merge and every release git tag land on the same latest dist-tag.
  • tools/install.sh always installs the registry latest dist-tag (no channel/version selector for end users; --dev --ref <branch> is a build-from-source developer path, not an end-user channel).
  • Result: there is no mechanical "stable" vs "next" distinction today — a user gets the same artifact either way.

Blocking design decision (owner: Jason, via Mos)

Documenting two honest paths requires first defining the channel scheme. Recommended:

  • npm dist-tags: main merges publish to @next (prerelease-suffixed version, e.g. 0.0.49-next.N); release tags publish to @latest. Then:
    • Stable → npm i -g @mosaicstack/mosaic (resolves latest = last tagged release)
    • Next → npm i -g @mosaicstack/mosaic@next
  • Installer: add --channel next|stable (default stable).
  • Docker: already has :latest (main) + :<tag> (release); add :stable / :next aliases if desired.

This is a publish.yml + install.sh change (CI/tooling lane, needs its own review) that must land before the README can honestly document @next.

Alternative (docs-only, no pipeline change): frame today's single latest channel as "next/rolling" and document pinning to a released version tag (@mosaicstack/[email protected]) as "stable." Honest but not a true parallel channel.

Acceptance criteria

  • Channel scheme decided (dist-tag split vs docs-only framing).
  • README documents a clearly labeled Stable install path and a Next install path.
  • If dist-tag split chosen: publish.yml + install.sh updated + tested first (separate PR/lane).
  • Docs-only change is README-scoped, low risk.

Labels: docs

## Summary The Mosaic Stack `README.md` should document install instructions for **two distinct channels**: the **stable release** and the **"next" (pre-release / bleeding-edge)** build — two clear install paths, not just the current single path. Requested by Jason (Discord 2026-07-16 21:26Z), tracked by Mos (orchestrator). ## Current state (as of `main` @ `59f5f51f`) - `@mosaicstack/mosaic` (the installable CLI) publishes to the Gitea npm registry via `.woodpecker/publish.yml`. - The publish step runs `pnpm ... publish` with **no `--tag`**, so **both** every `main` merge **and** every release `git tag` land on the **same `latest` dist-tag**. - `tools/install.sh` always installs the registry `latest` dist-tag (no channel/version selector for end users; `--dev --ref <branch>` is a build-from-source developer path, not an end-user channel). - Result: **there is no mechanical "stable" vs "next" distinction today** — a user gets the same artifact either way. ## Blocking design decision (owner: Jason, via Mos) Documenting two *honest* paths requires first **defining** the channel scheme. Recommended: - **npm dist-tags:** `main` merges publish to `@next` (prerelease-suffixed version, e.g. `0.0.49-next.N`); release **tags** publish to `@latest`. Then: - Stable → `npm i -g @mosaicstack/mosaic` (resolves `latest` = last tagged release) - Next → `npm i -g @mosaicstack/mosaic@next` - **Installer:** add `--channel next|stable` (default `stable`). - **Docker:** already has `:latest` (main) + `:<tag>` (release); add `:stable` / `:next` aliases if desired. This is a `publish.yml` + `install.sh` change (CI/tooling lane, needs its own review) that must land **before** the README can honestly document `@next`. Alternative (docs-only, no pipeline change): frame today's single `latest` channel as "next/rolling" and document pinning to a released version tag (`@mosaicstack/[email protected]`) as "stable." Honest but not a true parallel channel. ## Acceptance criteria - [ ] Channel scheme decided (dist-tag split vs docs-only framing). - [ ] README documents a clearly labeled **Stable** install path and a **Next** install path. - [ ] If dist-tag split chosen: `publish.yml` + `install.sh` updated + tested first (separate PR/lane). - [ ] Docs-only change is README-scoped, low risk. ## Labels: docs
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
code-be-01 (Mosaic fleet seat code-be-01) code-be-02 (Mosaic fleet seat code-be-02) code-infra-01 (Mosaic fleet seat code-infra-01) fargo fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) pepper rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) sanity scooby (Scooby) scrappy shaggy tiny velma veronica (Mosaic fleet seat veronica) vision woodpecker
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#805