FAQ

The questions that come up most often, each with the short answer and the page that carries the long one. For anything not covered here, the community lives on Discord.

What does dispat need before the first release?

A git repository with full history, one configuration file naming the package folders and the build and publish commands, and commits written as conventional commits. There is no runtime to install and no state file: the tags are the whole memory. Getting started walks the four steps.

Why did a package I did not touch release?

Three legitimate reasons, and the plan names each one in its reason field. The package shares a version group with something that moved (fixed group versioning, reported as W234); a provider's commit carried a propagation marker such as feat(core)^ (propagated from core); or a provider published in an earlier run whose leg for this package failed, and the run is discharging that debt (catch-up from core, reported as W193). dispat status shows the reason before anything runs.

Why does status show fewer packages when I run it inside a package folder?

Standing inside a package folder narrows the invocation to that package, exactly as --package would. A narrowed selection can also withhold a package whose providers are outside the selection (W230). Run dispat from the repository root for the whole plan, or pass --strict to refuse a selection that costs anything. Partial releases has the details.

Why did my manifest move to a provider version I did not release in this run?

That is the auto-version reconciliation pickup: when a provider released without you, your package's next release resolves every declared range to the provider's current published version, reported as W197. Lock-file scripts under syncLock choose no versions; they only make the lock follow the manifest. The changelog deliberately does not list the pickup, because the provider's own release documented it.

Why does a changelog entry say "No changes"?

A record entry is never empty, so a release with nothing for its notes to group states its cause instead: a version bump keeping a version group aligned, a version set by Release-As, a channel transition, or pending work its own reverts cancelled out. Records lists the exact lines.

How do I run a prerelease line, and how do I end it?

A channel directive on a commit starts the train: feat(core)%rc: releases 1.3.0-rc.0, later work continues it to rc.1, and each prerelease entry documents only its own changeset. A transition ends it: release(core)%rc>stable: graduates the train, and the stable entry collects the whole train into the one entry stable readers see. If a graduation is refused as backwards (E185, typically after an exact pin raised the train), pin the graduation itself with Release-As. Commits covers the directives.

A release failed halfway. What do I do?

Usually nothing but re-run. Packages that published keep their records, the failed ones and their dependants are skipped or failed, and the next run releases exactly what is still owed at the versions it was owed, labelled as catch-up. There is no repair command and no state to clean. Recovering from a failed run shows a full sequence.

Can I release only part of the monorepo?

Yes: --package, --space and --group narrow any command, and standing in a folder implies the narrowing. The plan reports what the selection costs, a split version group catches up on the next run (W231, W234), and --strict turns any cost into a refusal. Partial releases is the guide.

How do I stop something from releasing?

The ladder, from softest to hardest: Release-As: none holds a package without discarding anything, and Release-As: auto resumes it at everything accumulated; Deletes: discards one commit's record; cancel(scope) erases the pending ledger for a scope. All of them reach only work that has not shipped: released history is never retracted. Correcting a record covers the corrections.

Does dispat ever rewrite git history?

No. dispat only adds: a release commit, tags, changelog entries prepended to a file. Records that are wrong are corrected forward with Edits: and Deletes: footers in new commits, so the audit trail survives its own mistakes.

Which languages and package managers does it work with?

Any: a package is a folder and a stage is a shell command, so Go, npm, pnpm, Cargo, Maven, Python, Docker and the rest all sit in one dependency graph. Native manifest rewriting exists for package.json, go.mod, requirements*.txt, Dockerfiles and compose files; every other format is covered by the replace strategy or a flow.version script. The examples show one setup per ecosystem.

How do I pin the dispat version in CI?

The GitHub action takes a version input, the install script takes --version, and the container images ship one CLI version per image tag. With nothing pinned, both resolve the latest stable release.