Warn when deprecated options are passed to commands and improve their docs.

Review Request #14623 — Created Sept. 25, 2025 and updated

Information

RBTools
release-5.x

Reviewers

We currently allow for rbt options to be marked as deprecated, and we'll
display deprecation info in the documentation and help text for the option.
But we weren’t emitting any warnings when users actually passed them on
the command line. This change allows rbt to emit a deprecation warning
when a deprecated option is used.

This change also allows setting a replacement option and the version in
which the option will be removed. Our sphinx documentation building
functions and help text building logic have been updated to include these.

I decided to move our RBTools-specific option attributes out of
Option.attrs and made them direct attributes on the Option class
instead. This keeps a clearer separation from the argparse arguments
and lets us keep this information around after the Option is added to
the parser (previously we would strip all of our custom attributes
before adding an option to the parser). We also get easy typing on
these attributes now.

We also recently marked rbt login's --enable-logging as deprecated, and
this change defines its replacement (--debug) and removal version (6.0).

  • Tested rbt login -l saw the deprecation warning
  • Tested rbt login with options other than -l, saw no warnings
  • Ran unit tests.
  • Built docs and looked at options that have one or more of the custom
    RBTools attributes (config key, extended help, added in and the various
    deprecation related attributes).
Summary ID
Warn when deprecated options are passed to commands and improve their docs.
We currently allow for `rbt` options to be marked as deprecated, and we'll display deprecation info in the documentation and help text for the option. But we weren’t emitting any warnings when users actually passed them on the command line. This change allows `rbt` to emit a deprecation warning when a deprecated option is used. This change also allows setting a replacement option and the version in which the option will be removed. Our sphinx documentation building functions and help text building logic have been updated to include these. I decided to move our RBTools-specific option attributes out of `Option.attrs` and made them direct attributes on the `Option` class instead. This keeps a clearer separation from the `argparse` arguments and lets us keep this information around after the Option is added to the parser (previously we would strip all of our custom attributes before adding an option to the parser). We also get easy typing on these attributes now. We also recently marked `rbt login'`s `--enable-logging` as deprecated, and this change defines its replacement (`--debug`) and removal version (6.0).
15272d8ea34feef0a76480ffb72f551ef6c52af2
Description From Last Updated

Can we add a blank line above this?

daviddavid

This should come from collections.abc instead of typing

daviddavid

Can we use Mapping[...] instead of dict[...] here?

daviddavid
david
  1. 
      
  2. rbtools/commands/base/commands.py (Diff revision 1)
     
     
     
    Show all issues

    Can we add a blank line above this?

  3. rbtools/commands/base/options.py (Diff revision 1)
     
     
    Show all issues

    Can we use Mapping[...] instead of dict[...] here?

  4. 
      
maubin
david
  1. 
      
  2. rbtools/commands/base/options.py (Diff revisions 1 - 2)
     
     
    Show all issues

    This should come from collections.abc instead of typing

  3. 
      
maubin
Review request changed
Commits:
Summary ID
Warn when deprecated options are passed to commands and improve their docs.
We currently allow for `rbt` options to be marked as deprecated, and we'll display deprecation info in the documentation and help text for the option. But we weren’t emitting any warnings when users actually passed them on the command line. This change allows `rbt` to emit a deprecation warning when a deprecated option is used. This change also allows setting a replacement option and the version in which the option will be removed. Our sphinx documentation building functions and help text building logic have been updated to include these. I decided to move our RBTools-specific option attributes out of `Option.attrs` and made them direct attributes on the `Option` class instead. This keeps a clearer separation from the `argparse` arguments and lets us keep this information around after the Option is added to the parser (previously we would strip all of our custom attributes before adding an option to the parser). We also get easy typing on these attributes now. We also recently marked `rbt login'`s `--enable-logging` as deprecated, and this change defines its replacement (`--debug`) and removal version (6.0).
d8611fe93455105d6333a6fa533d85872ba6af5f
Warn when deprecated options are passed to commands and improve their docs.
We currently allow for `rbt` options to be marked as deprecated, and we'll display deprecation info in the documentation and help text for the option. But we weren’t emitting any warnings when users actually passed them on the command line. This change allows `rbt` to emit a deprecation warning when a deprecated option is used. This change also allows setting a replacement option and the version in which the option will be removed. Our sphinx documentation building functions and help text building logic have been updated to include these. I decided to move our RBTools-specific option attributes out of `Option.attrs` and made them direct attributes on the `Option` class instead. This keeps a clearer separation from the `argparse` arguments and lets us keep this information around after the Option is added to the parser (previously we would strip all of our custom attributes before adding an option to the parser). We also get easy typing on these attributes now. We also recently marked `rbt login'`s `--enable-logging` as deprecated, and this change defines its replacement (`--debug`) and removal version (6.0).
15272d8ea34feef0a76480ffb72f551ef6c52af2

Checks run (2 succeeded)

flake8 passed.
JSHint passed.
david
  1. Ship It!
  2.