ci(release): add an alpha (pre-release) dist-tag lane

.github/workflows/release.yml

@@ -25,8 +25,15 @@ jobs:
         run: |
           TAG="${GITHUB_REF_NAME}"
           VERSION="${TAG#v}"
+          # Dist-tag from any semver pre-release identifier so a pre-release NEVER moves
+          # `latest`: 4.0.0-alpha.0 → alpha, 4.0.0-rc.1 → rc, 3.5.0 → latest (no identifier).
+          DIST_TAG=$(printf '%s' "$VERSION" | sed -n 's/^[0-9.]*-\([A-Za-z]*\).*/\1/p')
+          [ -z "$DIST_TAG" ] && DIST_TAG=latest
+          PRERELEASE=false; [ "$DIST_TAG" = latest ] || PRERELEASE=true
           echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "dist_tag=${DIST_TAG}" >> "$GITHUB_OUTPUT"
+          echo "prerelease=${PRERELEASE}" >> "$GITHUB_OUTPUT"
 
       # Added this step to fix UnsupportedClassVersionError
       - name: Setup Java
@@ -77,11 +84,15 @@ jobs:
       - name: Publish to NPM
         run: |
           npm config set //registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}
-          npm publish --access public
+          npm publish --access public --tag "${{ steps.version.outputs.dist_tag }}"
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Build and Publish to Clojars
+        # Pre-releases (alpha) are npm/ESM-only — skip the Clojure jar. (The jar is for
+        # source-consuming CLJS apps, not the alpha audience; skipping also avoids
+        # re-deploying an unbumped jar version, which Clojars rejects.)
+        if: ${{ steps.version.outputs.prerelease == 'false' }}
         run: |
           clojure -T:build jar
           clojure -X:deploy
@@ -95,5 +106,6 @@ jobs:
           tag_name: ${{ steps.version.outputs.tag }}
           name: "v${{ steps.version.outputs.version }}"
           generate_release_notes: true
+          prerelease: ${{ steps.version.outputs.prerelease == 'true' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/RELEASING.md

@@ -20,6 +20,20 @@ Then:
 
 The `release.yml` workflow triggers on `v*` tags and publishes to npm, Clojars, and GitHub Releases. `pom.xml` is auto-generated by `build.clj` — do not edit it manually.
 
+### Alpha (pre-release) releases
+
+For shipping experimental work (e.g. the write-side `barebuild-action` / `barebuild-invalidate-on` elements) **without touching the stable `latest` tag**, the same `release.yml` derives the npm dist-tag from the version: any semver pre-release identifier (`X.Y.Z-alpha.N`) publishes to the `alpha` dist-tag, skips the Clojars deploy, and marks the GitHub release as a pre-release. A plain `X.Y.Z` is unaffected → `latest`, Clojars, normal release.
+
+Consumers opt in with `npm install @vanelsas/baredom@alpha`; a normal `npm install @vanelsas/baredom` keeps resolving the stable `latest`, and `^3.x` ranges never pick up a `4.0.0-alpha.N` (pre-releases are excluded from caret ranges).
+
+Use the **`4.0.0-alpha.N` lane** — it sorts above the whole stable `3.x` cadence, so routine `3.x` releases and the alpha never collide. Publish from the feature branch (e.g. `feat/barebuild-write-side`), not `main`:
+
+1. On the feature branch, bump **only `package.json`** → `"version": "4.0.0-alpha.N"`. Leave `build.clj` / `deps.edn` / `README.md` on the stable `3.x` line — Clojars is skipped for pre-releases, and the README documents the stable install. (The deliberate exception to the "all four locations" rule above.)
+2. Add a `## [4.0.0-alpha.N]` entry to `CHANGELOG.md`.
+3. Commit, then `git tag v4.0.0-alpha.N && git push origin <feature-branch> v4.0.0-alpha.N`.
+
+The existing `NPM_TOKEN` works as-is — `--tag` is just a publish flag on the same package/scope; no new permission needed. Verify after the run: `npm dist-tag ls @vanelsas/baredom` should show `latest: 3.x.y` **and** `alpha: 4.0.0-alpha.N`.
+
 ## Adapter releases
 
 Each framework adapter lives under `adapters/<name>/` and has its own workflow in `.github/workflows/release-<name>.yml`, keyed on `<name>-v<X.Y.Z>` tags: