Problem
The repo is positioned as a learning application to help someone "make a
decision whether to use base-cli", but it gives an evaluator none of the
information a real adoption decision needs:
- Maturity / stability is never stated.
pyproject.toml pins
base-cli>=0.4.3,<0.5; the published package is classified
"Development Status :: 4 - Beta". docs/compatibility.md explains the pin
mechanics but never tells the reader "this framework is pre-1.0 and the API
may change before 1.0" — which is the single most important fact for someone
deciding to build on it.
- Fit guidance is missing. Nothing says when base-cli is a good choice
(a team CLI with automation/JSON consumers, multiple subcommands, release and
redaction needs) versus when it is overkill (a one-off script, a single
command with no machine output).
- Cost of adoption is not discussed. Taking a dependency on base-cli means
tracking its release cadence and its <0.5 API line; the demo's own
compatibility CI exists precisely because this needs active maintenance. An
honest "what you take on" paragraph would help.
- Alternatives are not acknowledged. A reader comparing base-cli to plain
Click, Typer, argparse, or cleo has nothing here to frame the trade-off.
Suggested fix
Add docs/should-i-use-base-cli.md (linked prominently from README.md) with:
- Status & stability: current version line, pre-1.0 expectations, what
<0.5 means for callers, how breaking changes are communicated.
- Good fit / poor fit bullet lists.
- What adopting costs: dependency-tracking, version-range maintenance,
coupling to the framework's lifecycle model.
- How it compares: 3–4 lines each versus Click/Typer/argparse — what you
gain, what you give up.
Acceptance
- An evaluator can read one page and decide, with eyes open, whether base-cli
suits their project and what maintenance it implies.
Problem
The repo is positioned as a learning application to help someone "make a
decision whether to use base-cli", but it gives an evaluator none of the
information a real adoption decision needs:
pyproject.tomlpinsbase-cli>=0.4.3,<0.5; the published package is classified"Development Status :: 4 - Beta".
docs/compatibility.mdexplains the pinmechanics but never tells the reader "this framework is pre-1.0 and the API
may change before 1.0" — which is the single most important fact for someone
deciding to build on it.
(a team CLI with automation/JSON consumers, multiple subcommands, release and
redaction needs) versus when it is overkill (a one-off script, a single
command with no machine output).
tracking its release cadence and its
<0.5API line; the demo's owncompatibility CI exists precisely because this needs active maintenance. An
honest "what you take on" paragraph would help.
Click, Typer,
argparse, or cleo has nothing here to frame the trade-off.Suggested fix
Add
docs/should-i-use-base-cli.md(linked prominently fromREADME.md) with:<0.5means for callers, how breaking changes are communicated.coupling to the framework's lifecycle model.
gain, what you give up.
Acceptance
suits their project and what maintenance it implies.