Release

Releasing shellshare

A release is one command — make release — but the command is the easy part. The two things that actually need judgment, and the reason this skill exists, are picking the right version number and writing the release notes. Get those right and everything else is automation.

How a release works here

make release runs scripts/release.sh, which bumps the version in Cargo.toml, refreshes Cargo.lock, commits chore: release vX.Y.Z, tags vX.Y.Z, and pushes both atomically. The tag push triggers .github/workflows/release.yml, which runs the full e2e suite, builds binaries for all four platforms, builds the Docker image, publishes to npm, and creates the GitHub release. You do not build or upload anything by hand.

The script refuses to run unless you're on main with a clean working tree, and it pulls --ff-only first. So the release itself is safe by construction — the risk isn't a broken command, it's shipping the wrong version number or thin release notes, both of which are hard to walk back once npm and the GitHub release are public.

Step 1 — Confirm the ground is solid

Run these and read them before anything else:

git rev-parse --abbrev-ref HEAD        # must be main
git status --porcelain                 # must be empty
git fetch --tags origin && git log --oneline @{u}..HEAD   # must be empty (you're not ahead)
git describe --tags --abbrev=0         # the last released tag

If the branch isn't main or the tree is dirty, stop and surface that — don't try to work around release.sh's guards, they exist for good reason.

Step 2 — Choose the version (this is the real work)

Look at everything since the last tag:

LAST=$(git describe --tags --abbrev=0)
git log --oneline "$LAST"..HEAD

shellshare does not follow textbook semver. The rule is specific and you must apply this one, not the generic one:

• MAJOR (e.g. 3.3.0 → 4.0.0) — reserved for changes that break old shellshare CLI binaries talking to the ingest endpoint /ws/r/:room. That means a breaking change to src/cli/, the ingest handshake, the ack semantics, or the wire frame format in src/protocol.rs. Verify with:

  git diff "$LAST"..HEAD -- src/cli/ src/protocol.rs

  Breaking the viewer WebSocket protocol (/ws/v/r/:room), templates, or any server internals does NOT justify a major bump. Browsers always load the viewer page from the same server, so page and protocol ship in lockstep — there is no "old viewer" in the wild to break. A commit literally labeled BREAKING can still be a minor release if old CLIs keep working (this is exactly why the Socket.IO→raw-WebSocket viewer rework shipped as 3.3.0, not 4.0.0).

• MINOR (e.g. 3.2.0 → 3.3.0) — any new user-facing capability that doesn't break old CLIs: a feat: commit, a new flag, a new subcommand, a new endpoint. Additive changes to the CLI count here too, even substantial ones (e2e encryption shipped as a minor because old binaries still broadcast fine with --disable-encryption semantics intact).

• PATCH (e.g. 3.3.0 → 3.3.1) — the release contains only fixes, perf work, refactors, style, tests, docs, or chores. No new capability. This is what bare make release produces by default.

When in doubt between minor and patch, ask: "could a user do something new after upgrading?" Yes → minor. No → patch. When in doubt between major and minor, ask: "would someone's already-installed shellshare binary stop broadcasting against the new server?" Only a clear yes → major.

Worked examples from real history:

Decide the bump, then state your reasoning to the user in one or two sentences and name the proposed version. Because a release is public and effectively irreversible (npm + GitHub release + git tag), wait for the user to confirm the number before running anything. This is the one place to be sure rather than fast.