Document drift command marks

[sevdog]

What problem does this solve?

Currently the drif command outputs a !! for blocking drift and a ~ for a non-blocking one.

However this is not documented, it can only be seen in the code:

django-orm-lens/cli/django_orm_lens/drift.py

Line 305 in 9e25025

mark = "!!" if d.is_blocking else " ~"

Proposed solution

Add a description of the meaning of marks in the command help or in the summarized output, to help user to better identify issues.

Alternatives you considered

No response

[FROWNINGdev]

Good catch, and thanks for linking the exact line — you were right that the source was the only place the marks were explained.

Fixed in ecc75dd. You asked for the help text or the output; it went into both, because the marks appear in the output but people look for meaning in --help:

$ django-orm-lens drift
!! blocking — models declare something no migration creates; it will not exist at runtime
 ~ advisory — migrations keep something models no longer declare; harmless at runtime

!! blog.post:
     declared but never migrated: author
       the column will be missing at runtime

summary: 1 model(s) drifted, 1 blocking, 2 migration(s) replayed

drift --help now prints the same two lines plus the rule that follows from them — only blocking drift fails the build, --exit-zero reports it without the non-zero exit.

Two details you may care about, since you maintain a migration-check Action yourself:

• The legend is a module constant next to the marks, imported by the CLI rather than retyped. A second copy in the argument parser is exactly how these went undocumented in the first place, and it would rot the same way. The tests assert the legend against the mark each entry actually carries, not against a hardcoded string.
• No legend on a clean run — nothing is marked there — and JSON output is unchanged, since it always carried "blocking": true | false outright.

On main now, ships in the next release. Credited you in the changelog and the roadmap.