Beta Release

Beta Release

Overview

This plugin ships pre-release builds via BRAT so the maintainer (and any opted-in reporters) can test changes for a few days before stable. Stable users continue to receive only the version listed in manifest.json via Obsidian's community plugin store.

Pair skill: bump-version handles the stable bump that closes out the beta cycle.

The pattern this repo uses

The default-branch manifest.json stays at the previous stable. package.json carries the X.Y.Z-beta.N semver-prerelease. A tag X.Y.Z-beta.N triggers release.yml, which auto-creates a draft release whose asset manifest.json is version-synced to the tag and is auto-marked pre-release for -beta/-alpha/-rc tags; the maintainer just reviews and publishes.

The key insight: the default-branch manifest.json and the release-asset manifest.json are different copies and are meant to differ during a beta — branch stays at stable (store-safe), asset matches the tag (BRAT-correct).

Why this pattern (verified against BRAT's official guide, not guessed):

• Obsidian's community plugin store reads manifest.json on the default branch — keeping it at the stable version is what blocks the beta from reaching all users (BRAT guide: "Obsidian will pick up an update once the manifest.json in the default branch of your repository changes."). The store does not read pre-release assets, so the asset version is free to be the beta version.
• BRAT uses the release tag as the source of truth and "validates both the release tag version and the version in the manifest.json asset … notifying users of the discrepancy" when they disagree. So a stable asset manifest on a -beta tag still works (testers get the right main.js and BRAT shows the tag version) but shows testers a needless version-mismatch warning — which is why release.yml now syncs the asset manifest to the tag (BRAT guide best practice: "Always ensure the version in your released manifest.json matches your release tag version").
• manifest-beta.json is not used and should not be — BRAT ignores it from v1.1.0 on (legacy). A survey of 8 popular plugins found only dataview still ships one. release.yml's asset-sync replaces what manifest-beta.json used to do.

Sources: BRAT Developer Guide, BRAT pre-release/version-picker update.

Reading current release state (don't re-derive — this tripped past sessions up)

The default-branch manifest.json version is not a reliable indicator of the beta line: betas are cut without bumping it, so a X.Y.Z-beta.N tag's committed manifest still says the previous stable. Use these instead:

• What's been cut: git tag --sort=-creatordate
• Draft vs published / prerelease: gh release view <tag> --json isDraft,isPrerelease,publishedAt — NOT gh release list (it lists drafts too) and NOT the changelog/manifest.
• CHANGELOG caveat: a dated ## [X.Y.Z] - YYYY-MM-DD heading can exist before X.Y.Z ships (the beta-prep step renames ## [Unreleased] early), so a dated heading does not mean that version is released.

Why it matters: wrong release-state assumptions produce wrong user-facing guidance — e.g. telling the maintainer to "publish the draft" when it's already live, or sending an email that points at a release link that 404s.

When to Use

• User asks for "beta release", "release X.Y.Z-beta.N", "ship a beta", "BRAT 으로 테스트"
• A batch of fixes/features has landed on main and you want maintainer-only test exposure before stable

If the user just says "release 1.3.0" (no beta), use bump-version instead.

Process

0. Sanity check before bumping

• Confirm main is the branch and has the work to ship.
• git log --oneline <last-stable-tag>..HEAD — eyeball the commit set.
• Scan every commit message in that range for Closes #N / Fixes #N / Resolves #N. If any appear, those issues will auto-close the moment you push to main from the beta-bump commit onward — which is wrong for a beta (the issue should close on stable, not on the beta build). If you find any, plan to reopen those issues after pushing (see step 6) and use Refs #N in future commits.

1. Determine the beta version

• Default N=1 for the first beta of a given X.Y.Z. Subsequent betas of the same X.Y.Z increment N.
• If the user gives an explicit version (e.g. /beta-release 1.3.0-beta.2), use it.

2. Update files

• package.json → "version": "X.Y.Z-beta.N"
• manifest.json → leave at the previous stable (do not change)
• CHANGELOG.md → rename the existing ## [Unreleased] section to ## [X.Y.Z] - YYYY-MM-DD (the stable header, not -beta.N). If a ## [X.Y.Z] section already exists — you're shipping beta.2+ of the same X.Y.Z, so an earlier beta already created it — do NOT rename; that would produce a duplicate [X.Y.Z]. Instead merge the ## [Unreleased] entries into the existing ## [X.Y.Z] section under the matching categories, then delete the now-empty [Unreleased] header (keep the existing date; bump-version finalizes it at stable). Feature sessions maintain ## [Unreleased] as work lands (see repo CLAUDE.md → Changelog), so the entries should already be present — add any that were missed. Reuse the [X.Y.Z] section as-is for the eventual stable bump. Follow the existing categories (Added / Changed / Improved / Fixed) and reference issue numbers (#N). Write from user perspective — see bump-version for the same conventions.

Verify each entry against the user-facing surface before finalizing. Commit descriptions tell why and how a change was made; CHANGELOG entries tell what the user sees. These diverge in small but visible ways — e.g. a UI control described as a "slider" that's actually addText (number input); a fix said to affect "the sidebar" that also affects the in-document panel; a setting whose label in code differs from the working name in the commit. For each entry, open the component that implements the change and confirm control type, exact label, and which views are affected. The same verified entry text feeds into the release body in step 5 — getting it right here means the release body is correct by construction.

3. Commit

git commit -m "chore: prepare X.Y.Z beta

- package.json: A.B.C -> X.Y.Z-beta.N
- manifest.json: stays at A.B.C so the community plugin store does not
  push the beta to stable users; BRAT testers receive this build via the
  X.Y.Z-beta.N prerelease.
- CHANGELOG entry for X.Y.Z is drafted in place and will be reused at
  stable release time."

4. Push and tag

git push origin main
git tag X.Y.Z-beta.N
git push origin X.Y.Z-beta.N

The push of the tag triggers .github/workflows/release.yml → builds with npm run build → version-syncs the asset manifest.json to the tag (the committed default-branch file is untouched) → adds --prerelease for -beta/-alpha/-rc tags → creates a draft release with assets main.js, manifest.json, styles.css.

Wait for the workflow with gh run watch <id> (or gh run list --workflow=release.yml --limit 1).