Breaking changes waiting for the next major release. Every published crate shares the 7.x
line, and Cargo treats any 7.x as compatible with any other, so anything here would break
an adopter's cargo update if it shipped sooner. mise run lint:semver catches the ones
that reach a pull request.
When a change can't go out without breaking the public API, ship the part that doesn't break now and add the rest here: what changes, why, and what adopters should do.
Binary size work on the oxc CLIs (oxlint and oxfmt) found that the derive-emitted tables are
now the largest remaining usage cost: about 22 KB of data plus about 11 KB of relative
relocations in oxlint, roughly 550 bytes per flag. They are large because every field is a
fat reference or a u64, and each reference needs a relocation in a position-independent
binary.
- What changes:
FlagandFlagMeta(and the matching command tables) store offsets into one shared string table, with narrower integers forkey, counts and indices, instead of&'static str,&'static [..]andu64fields. - Why it breaks: those fields are public, so changing their types breaks any code that builds or reads a table by hand. Derived code is unaffected.
- Estimated saving: about 4 KB on oxlint from
FlagMetaalone, more onceFlagfollows. - What adopters do: nothing if they use the derives. Hand-written tables regenerate or move to the constructor functions.
The derive emits a FLAG_<n>_BINDING_TYPE function returning a type name string for every
flag, stored in the public Flag::binding_type: Option<BindingType> field. Only derive-generated
code reads it: it compares two flags' binding types to decide whether a child command's
redeclaration of a global flag is compatible. Parser never reads it.
- What changes:
Flag::binding_typeand theBindingTypetype are removed, saving one function and one string per flag. - Open design question: the comparison cannot simply move into the derive's expansion. A parent derive does not see a subcommand's definition or a flattened struct's fields, so it has no types to compare while it expands. The check that replaces it has to run where both flags' types are visible, for example a generated const assertion over an associated item on the value type, and it has to keep today's diagnostic. Until that exists, this item is a candidate, not a plan.
- Why it breaks: both items are public. Any code that names
BindingTypeor sets or readsFlag::binding_typestops compiling, and a hand-builtFlagliteral that sets the field does too. - What adopters do: a hand-built
Flagdrops thebinding_typefield. Whether derive users see any difference depends on the replacement check: it must accept and reject the same redeclarations as today.
Parser::with_action_errors carries the default_flag_route and sigil-argument logic that only
some CLIs use, roughly 5 KB per binary. Dropping it where unused means making Parser
generic over a const set of behaviours that derives choose.
- What changes:
Parsergains const generic parameters. - What the defaults keep working: with defaults on the new parameters,
Parser<'t, 'a, 'v>written in a type position, a struct field or animpl Trait for Parser<'t, 'a, 'v>that only has to cover the default choices keeps compiling, and values built throughParser::newinfer the parameters. - What needs new parameters: an
implor function that must accept every choice of the behaviours, rather than only the defaults, has to be generic over the new parameters. - Why it breaks anyway: a new generic parameter on a public type is a major change to
cargo semver-checks, whatever the defaults preserve. - What adopters do: nothing for code that only constructs a
Parserand callsnext_event, or that names it with the default spelling. Code generic over every choice adds the parameters.
Two more public types are larger than they need to be, found by the same size work:
Event::ClauseSeparatorcarries aClauseby value, which makesEvent80 bytes andResult<Option<Event>, Error>larger and costlier to copy on everynext_event. Carrying a&Clauseshrinks both. Breaking because the variant's payload type is public.help::Styleembeds aPalette(four&'static str) and is 72 bytes, copied by value through the help renderer. Thepalettefield is private, so shrinking the embedded copy is not breaking by itself. The public API in the way isStyle::palette(self, palette: Palette), which takes aPaletteby value. Storing a&'static Palettemeans taking&'static Palettethere, so a caller that builds a custom palette at runtime has to promote it to astaticorconst(aconstworks, sincePalette's fields are&'static str), or leak it.Palette's own public fields do not change.
The flag table item above also has two specifics: FlagMeta holds 13 bool fields that a u16
bitset would pack (a single byte holds eight), and FlagMeta.accepted_choices and choices
overlap. Flag.name is only sometimes redundant: it matches longs[0] for most flags, but the
derive keeps explicit names, and for a short-only flag it holds the short letter, which help
and the redeclaration check read. A saving here would drop name only where it equals
longs[0] and keep a fallback for every other flag. ArgMeta (456 bytes) embeds its rarely used
fields inline instead of behind a shared extra record, the way FlagMeta uses FlagExtra.
usage::go::generate returns a String, so it has no way to refuse a spec it cannot generate
correctly. A spec with both unknown_env and a mount is the first such case: the Go generator
does not emit mounted commands, so it cannot know their variables, and the generated parser
would refuse variables usage-lib accepts. generate_with_types, which the CLI calls, already
returns an error for it.
- What changes:
generatereturnsResult<String, String>and refuses whatgenerate_with_typesrefuses. - Why it breaks: the return type of a public function changes.
- What adopters do: handle the error, or call
generate_with_typeswith an empty map today.
usage_rs::completion::Completion::run writes the script and the --install report to the same
writer, so a tool that passes stdout prints installed /path there. usage generate completion --install keeps stdout empty and reports on stderr. Completion::run_split takes both writers
and is the recommended call today.
- What changes:
runandrun_insend the install report to stderr and only the script toout, or drop the single-writer form in favour ofrun_split. - Why it breaks: a caller that reads the report from
outstops receiving it there. - What adopters do: call
run_splitnow, with stdout and stderr.