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).