Discourse/discourse
Discourse/discourse
0
0
Fork 0
mirror of https://github.com/discourse/discourse.git synced 2026-08-04 10:39:43 +08:00
Code Packages Activity Actions
discourse/migrations/AGENTS.md
Gerhard Schlager 15be00530a MT: Add disco check — a single entrypoint for all schema and converter checks 
Until now, nothing made sure that the schema config, the generated files
and the converters stayed in sync. `schema diff` only showed the
differences, the regeneration check in CI didn't notice changes that
produced the same generated files, and the reference converter could get
out of sync with the schema without anyone noticing. Each check only
compared against the previous step, so if one step was already stale, the
checks after it passed even though they ran against stale data.

This adds `disco check`. It runs all checks in dependency order (pending
migrations, config validity, config vs. database drift, committed
generated files, and converter column coverage, including columns and
models that don't exist anymore) and stops at the first check that fails.
On failure it prints copy-paste commands to fix the problem, for example
the new `disco schema unignore`. CI runs the same command, so if it passes
locally, the CI check passes too.
2026-06-11 21:27:17 +02:00

1.6 KiB
Vendored
Raw Permalink Blame History

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

  • 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.