Core releases

Core uses Sampo changesets and a short-lived release PR against main. A release is the exact merged commit, identified by a v tag. The npm packages share a version; the course format/schema version is separate and changes only through the format migration process.

While implementing a change

Add one Markdown file under .sampo/changesets/ for an observable change. Describe the resulting behavior in English. Use patch for a fix, minor for a compatible feature, and major for an incompatible public interface. Internal changes can omit a changeset. Do not infer a release from commit counts or implementation size.

pnpm exec sampo add -p npm/elabora -p npm/@elabora/core -b patch -t Fixed -m "Explain the corrected behavior."

The fixed group in .sampo/config.toml advances all package versions together. Target the root package as well as the affected packages so the aggregate changelog includes the description. Work before versioned releases is kept in Development history. New version entries are generated by Sampo; do not maintain the same change both there and in a changeset.

Prepare a release

Start a branch such as release/core-0.1.1 from current main. Keep unrelated work out of it. Inspect pending changesets and run:

pnpm run release:prepare
pnpm run release:check -- --required
pnpm run docs
pnpm test
pnpm run typecheck
pnpm run test:e2e
pnpm run test:matrix

Review the resulting versions, lockfile and generated changelogs. Check that breaking changes explain migrations. Commit the prepared files, push the branch and open a PR against main. Include the version, changes, validation and any unresolved release configuration. Preparing a release does not mean merging or publishing it.

If more changes land before the release, recreate the branch from current main and prepare it again: running Sampo a second time on a prepared branch bumps the version once more (0.1.1 becomes 0.1.2). The released contents must still agree with the reviewed notes.

Publication

Merging an in-repository PR whose branch starts with release/core- triggers .github/workflows/release.yml. It reruns the core checks on the exact merged commit, on Linux and Windows (macOS runs weekly and when CI is dispatched by hand: its minutes cost ten times more), then creates one tag, v<version>, and a GitHub Release with the root changelog entry. The packages share that version and are all private, so they have no tags of their own; release:check refuses a package that is not private. Existing tags are never moved. The workflow can also be dispatched manually on main, for the commit at its head.

This setup does not publish packages to npm. Registry publication, package contents and npm authentication require a separate decision before enabling sampo publish. A public repository and a package published on npm are different distribution choices.

The desktop application can ship any explicitly pinned, tested core commit. Its product notes include only changes between the core revisions delivered in consecutive app versions; the core’s independent release schedule does not force an app update.

Agent entry point

The repository skill at .agents/skills/release-core/SKILL.md describes preparation and recovery. Any agent can read it directly; the workflow uses Git, npm and the GitHub CLI without requiring a particular agent runtime. Ask only for missing release intent, credentials or decisions that cannot be inferred from the changes. Never invent a signing result, a test result or a published version.