Skip to content

A platform for community discussion. Free, open, simple.

1.9 KB
Raw Blame

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 name on commands. Nested#parse instantiates a sub-command with name: (its invocation name), which Samovar stores and exposes as name. So don't declare a positional one :name on a disco command — when the argument is omitted the accessor silently reads back the command's own name (e.g. a schema add command would read back "add") instead of nil. Name the positional something else (one :table_name, …).

  • Samovar positionals are never required. Don't use one :x, required: true — it raises during parsing, before call runs, which breaks the -h/--help handling. Leave positionals optional and validate them at the top of call with require_positional! (see Migrations::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/--help option. The option hoisting in Command#parse moves recognized flags to the front, so a group-level help option steals --help from the subcommands — group sub --help would run the subcommand instead of printing its help. Leave groups without options; a bare group --help surfaces as an unparsable token, which Bootstrap turns into usage with exit 0.