A platform for community discussion. Free, open, simple.
Migrations Tooling — Agent Guide
Start with README.md — it is the single source of truth for this
project: gem layout and namespaces, the disco CLI, converters, the schema DSL,
and the install / test / lint workflow.
This file is reserved for agent-specific guidance that does not belong in the README (conventions, gotchas, do/don't notes for automated contributors).
Gotchas
Preserve source user IDs when possible. Keep creator/owner user IDs as optional IntermediateDB attributes when the destination table supports them. The importer should map a supplied ID and fall back to the system user when it is absent or cannot be mapped.
Samovar reserves
nameon commands.Nested#parseinstantiates a sub-command withname:(its invocation name), which Samovar stores and exposes asname. So don't declare a positionalone :nameon adiscocommand — when the argument is omitted the accessor silently reads back the command's own name (e.g. aschema addcommand would read back"add") instead ofnil. Name the positional something else (one :table_name, …).Samovar positionals are never required. Don't use
one :x, required: true— it raises during parsing, beforecallruns, which breaks the-h/--helphandling. Leave positionals optional and validate them at the top ofcallwithrequire_positional!(seeMigrations::CLI::Command); it raises a presentable error, so the user gets a clean message instead of a backtrace.Don't give command groups a
-h/--helpoption. The option hoisting inCommand#parsemoves recognized flags to the front, so a group-level help option steals--helpfrom the subcommands —group sub --helpwould run the subcommand instead of printing its help. Leave groups without options; a baregroup --helpsurfaces as an unparsable token, whichBootstrapturns into usage with exit 0.