Skip to content

Getting started ​

This tutorial cuts a real release of a small repo using only tarsi-serve — install, wire check, plan, dry-run, release, verify. The repo should use conventional commits.

1. Install tarsi-serve ​

There is no tarsi CLI — the surface is tarsi-serve, an ndjson ops binary with a one-shot front door. It ships as a tamias pack (libraries/tarsi, type: files declaring tarsi-serve as a tools/bin/<triple>/ payload bin):

bash
# From a tarsi checkout:
cargo xtask pack    # release-build → libraries/tarsi/tools/bin/<triple>/
tamias install ./libraries/tarsi   # deploys `tarsi-serve` onto PATH

Dev shortcut without tamias: cargo xtask install puts a release tarsi-serve in ~/.local/bin.

2. Check the wire ​

bash
tarsi-serve manifest
# → {"name":"tarsi-serve","version":"…","ops":["manifest","profiles","plan","changelog","notes","release"]}

Two modes: no args = ndjson JSON-lines loop on stdio ({"op": …, "params": …} in, {"ok": …, "result"|"error"} out); tarsi-serve <op> [--dir D] [--set k=v]… [--yes|--dry-run] = one-shot argv — --yes maps to dry_run: false, --dry-run forces the default. See Drive tarsi-serve ops for the full surface.

3. Prepare the repo ​

The repo needs a tarsi.toml. The minimal useful one:

toml
# tarsi.toml
[publish.crates]
enabled = false

[publish.ghreleases]
enabled = false

Tag-only releases are the org convention (ADR-0004); without the enabled = false lines both publish targets default to on. Units default to cargo workspace members — for a non-cargo repo, declare them explicitly (see Write a tarsi.toml).

Make sure the history you want released is conventional:

bash
git log --oneline
# feat(api): add retries        → minor bump
# fix(core): handle empty body  → patch bump
# chore: tidy imports           → no release on its own

4. Plan ​

bash
tarsi-serve plan --dir .

Read the result. Each unit in plan.units carries:

  • spec — resolved unit (name, path, tag format, publish targets)
  • bump — major / minor / patch / none
  • new_version — the version the bump would write
  • tag — e.g. my-unit-v1.2.0
  • releases — whether this unit actually releases
  • changelog_markdown — the rendered changelog section
  • commits — how many commits were attributed

plan.unattributed lists commits that matched no unit's paths — repo-root files land there. plan.steps is the mutation sequence release would run.

Nothing has been written. This is the review gate — always plan before release.

5. Preview the notes ​

bash
tarsi-serve changelog --dir .   # per-unit {unit, version, tag, markdown}
tarsi-serve notes --dir .       # concatenated release notes

6. Dry-run the release ​

bash
tarsi-serve release --dir .

release is dry-run by default — this executes the full plan and runs every publish target in dry-run mode, reporting what would happen, and writes nothing. Equivalently over ndjson:

json
{"op":"release","params":{"dir":".","dry_run":true}}

7. Release for real ​

Only after the plan looks right and a human approves:

bash
tarsi-serve release --dir . --yes

--yes is dry_run:false. The mutation phase, in order:

  1. Write CHANGELOG.md sections per releasing unit (created files are tracked for rollback).
  2. Bump versions in manifests via toml_edit (comments preserved).
  3. Stage only the touched files — CHANGELOG.md/Cargo.toml per unit plus root manifests — never git add -A.
  4. Commit chore(release): bump versions.
  5. Tag each releasing unit ({unit}-v{version}).
  6. Push branch + tags before publishing — GitHub Releases auto-creates tags at remote HEAD otherwise.
  7. Run publish targets (crates.io, GitHub Releases) against the pushed commit.

The result reports steps_run, per-target publish reports, and — on failure — rolled_back or a manual-cleanup note for partial publishes.

8. Verify ​

bash
git tag -l '*-v*' | tail
git log --oneline -3
tarsi-serve plan --dir .   # now: nothing to release

The latest-tag-per-unit range means a second plan finds no new commits since the tags you just pushed.

What you now know ​

  • tarsi-serve is the whole surface: one-shot argv ops plus an ndjson loop, dry-run by default.
  • plan is the review gate — per-unit bump, version, tag, changelog, and the exact mutation sequence release would run.
  • release --yes mutates in order: changelogs → manifest bumps → staged commit → tags → push → publish — with rollback reporting.
  • Re-running plan after a release finds nothing new: latest-tag- per-unit ranges are the idempotency boundary.

Next steps ​

MIT licensed — part of the 9aia GAIA stack.