stakk follows semantic versioning. This document is the contract: what a script, an agent or another tool may rely on, and what may move under it.
The wording of this document is not itself stable — it is a stakk docs topic,
and those may be rewritten at any time.
What it describes is; the contract changes in a release that says so.
Changing any of these needs a major release.
- Subcommand names, their aliases, and their flags, long and short forms alike. Removing an alias is as breaking as removing a flag.
STAKK_-prefixed environment variables, andFORGEJO_TOKEN. The GitHub token variables (GH_TOKEN,GITHUB_TOKEN,GH_ENTERPRISE_TOKEN,GITHUB_ENTERPRISE_TOKEN,GH_HOST) follow the GitHub CLI's names and are stable for as long as it keeps them.- Config file keys and their defaults. The list:
stakk docs config. One default is exempt:native_stacksisignorewhile GitHub's stacked pull requests are a public preview, and may becomeautoin a minor release once they leave it. The release that flips it says so in the changelog; nothing else about the key changes. - The
stakk graphJSON document under itsschema_version— field names, types and meanings. Currently3, reported by both the sparsejsonand thejson-fullprojection; sparse stays a strict subset of full. The order ofstacks[]is not part of this. Field by field:stakk docs graph. - The render context of
--template-pathtemplates. The top-level namesstack,stack_size,default_branch,current_bookmarkandstakk_url; on eachstackentrybookmark_name,pr_url,pr_number,title,base,is_draft,position,is_currentandis_leaf; and the trunk-first order ofstack. A name may be added in any release; renaming or removing one, or reorderingstack, needs a major. The built-in template's text is not covered — see below. - The JSON handed to
--bookmark-commandon stdin, under its ownschema_version(currently1). The schema is instakk submit --help. - Exit codes:
0success,1failure,130interrupted.2is clap's usage-error convention and follows clap, not this contract. Details:stakk docs scripting.
These may change in any release.
- The rendered text of
stakk docsand--help. Only thestakk docs <topic>invocation shape is stable. - The built-in stack comment template. What it renders may change in any release; the context it renders from is stable (above).
- The template language.
--template-pathtemplates are rendered by minijinja, so what its filters, tests and operators do follows the minijinja version stakk is built with. A release that updates minijinja may change how the same template renders a given context. - The order of
stacks[]in thestakk graphJSON. Choose a stack by its bookmarks or contents, never by index. - The
prettyoutput ofstakk graph.--format=jsonis the one for a program. - The TUI layout and keybindings.
- Spinner and progress text.
- Diagnostic codes (
stakk::…) and error wording. A code is still what a program should match on; prose may change silently, and a code that is added, split, merged or renamed is listed in the changelog. Treat an unknown code as a plain failure — the exit code is the signal. - Advisory warnings on stderr. They come and go; stderr output is not failure, the exit code is.
- The server-side behaviour behind
--native-stacks. The flag and its values are stable surface, but GitHub's stacked pull requests are a public preview, so what a registered stack looks like and when GitHub retargets or rebases can move without a stakk release, and stakk may change how it converges the stack (create, append, dissolve-and-recreate) in any release.
Raising the minimum supported jj version. The check is warn-only, so the floor can move in any release — normally the one that adopts a newer jj's behaviour.