Skip to content

breaking change: the bare command introduces the tool #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
obarlik merged 1 commit into from
Aug 29, 2026
Merged

breaking change: the bare command introduces the tool #5

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions project-type/TOOL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,15 @@ contains and hold the shape with a test across several version strings.
prints it, the others do too. *Incident: the banner appeared on `run` and
not on `qualify`, which takes just as long.*

**The bare command introduces the tool.** Typing the name with no
arguments is a reader asking what this is, not a mistake. Answer with the
mark and the command list on **stdout**, exit **0**. A wrong command or a
missing flag stays an error on stderr with a non-zero exit. *Incident: the
bare command answered with the argument parser's two-line error and exit
2, naming `cmd` — an internal variable — as the thing that was missing;
the tool's first contact with a stranger was a failure, and the one place
it named an implementation detail at them.*

**One entry point, named after the tool.** `tool <command>`, not
`python -m package.module`. *Incident: a line published as a tool required
the reader to know four separate module paths, none of them discoverable
Expand Down