Summary

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

Review Request #14623 — Created Sept. 25, 2025 and submitted Dec. 10, 2025, 6:04 a.m.

Information

Owner

maubin

Repository

RBTools

Branch

release-5.x

Bugs

Depends On

Reviewers

Groups

rbtools

People

Description

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

Testing Done


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

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).	71e1b5c3cc65d809f7da5e8de88afcf8562c5b48

Summary

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

71e1b5c3cc65d809f7da5e8de88afcf8562c5b48

Issues

Description	From	Last Updated
Can we add a blank line above this?	david	Sept. 26, 2025, 7:58 a.m.
This should come from collections.abc instead of typing	david	Sept. 29, 2025, 6:07 a.m.
Can we use Mapping[...] instead of dict[...] here?	david	Sept. 26, 2025, 8:01 a.m.
This might be from a different change, but this should be 5.4, no?	david	Nov. 11, 2025, 3:07 a.m.
This should be docutils.nodes.paragraph.	chipx86	Nov. 19, 2025, 6:01 a.m.
The ] should be on the next line.	chipx86	Nov. 19, 2025, 6:01 a.m.
) should be on the next line for a multi-line string.	chipx86	Nov. 19, 2025, 6:02 a.m.
Do we have a local logger we can use?	chipx86	Nov. 19, 2025, 6:10 a.m.
Will this work? all_options += item.option_list Same in other code paths doing this.	chipx86	Nov. 19, 2025, 6:35 a.m.
This can be combined to one statement now.	chipx86	Nov. 19, 2025, 6:38 a.m.
Can you make this a multi-line string with the strings on their own lines?	chipx86	Nov. 19, 2025, 6:39 a.m.

flake8 passed.

JSHint passed.

rbtools/commands/base/commands.py (Diff revision 1)
The issue has been resolved. Show all issues
```
Can we add a blank line above this?
```
rbtools/commands/base/options.py (Diff revision 1)
The issue has been resolved. Show all issues
```
Can we use Mapping[...] instead of dict[...] here?
```

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).	f5af1a0f4b96e06beaec8cc8aface92aa9acb8b1
	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

Diff:

Revision 2 (+1286 -106)

Show changes

	docs/rbtools/_ext/rbt_commands.py
	rbtools/commands/login.py
	rbtools/commands/base/commands.py
	rbtools/commands/base/options.py
	rbtools/commands/tests/test_command_initialization.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

rbtools/commands/base/options.py (Diff revisions 1 - 2)
The issue has been resolved. Show all issues
```
This should come from collections.abc instead of typing
```

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

Diff:

Revision 3 (+1286 -106)

Show changes

	docs/rbtools/_ext/rbt_commands.py
	rbtools/commands/login.py
	rbtools/commands/base/commands.py
	rbtools/commands/base/options.py
	rbtools/commands/tests/test_command_initialization.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

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).	15272d8ea34feef0a76480ffb72f551ef6c52af2
	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).	ba2deda4598c0829cb6c26618cdfa952949257d2

Diff:

Revision 4 (+1278 -100)

Show changes

	docs/rbtools/_ext/rbt_commands.py
	rbtools/commands/base/commands.py
	rbtools/commands/base/options.py
	rbtools/commands/tests/test_command_initialization.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

rbtools/commands/login.py (Diff revision 3)

The issue has been dropped. Show all issues

This might be from a different change, but this should be 5.4, no?

maubin Nov. 11, 2025, 3:07 a.m.

Yeah it should be, this gets fixed in a later change in my stack.

Ship it!

```
Ship It!
```

Very nice improvements. I have a few small stylistic tweaks to suggest.

docs/rbtools/_ext/rbt_commands.py (Diff revision 4)
The issue has been resolved. Show all issues
```
This should be docutils.nodes.paragraph.
```
rbtools/commands/base/commands.py (Diff revision 4)
The issue has been resolved. Show all issues
```
The ] should be on the next line.
```
rbtools/commands/base/commands.py (Diff revision 4)
The issue has been resolved. Show all issues
```
) should be on the next line for a multi-line string.
```

rbtools/commands/base/commands.py (Diff revision 4)

The issue has been dropped. Show all issues

Do we have a local logger we can use?

maubin Nov. 19, 2025, 6:44 a.m.

We use the root logger everywhere else in this file, and we do some setup for it in BaseCommand._init_logging().

On a sort of side note I do see that we have self.log = logging.getLogger('rb.%s' % self.name) in the init method for BaseCommand, but we don't use that logger anywhere in the RBTools codebase. I don't really wanna touch that in this change though.

rbtools/commands/base/commands.py (Diff revision 4)

The issue has been resolved. Show all issues

Will this work?

all_options += item.option_list

Same in other code paths doing this.

rbtools/commands/base/options.py (Diff revision 4)
The issue has been resolved. Show all issues
```
This can be combined to one statement now.
```
rbtools/commands/base/options.py (Diff revision 4)
The issue has been resolved. Show all issues
```
Can you make this a multi-line string with the strings on their own lines?
```

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).	ba2deda4598c0829cb6c26618cdfa952949257d2
	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).	71e1b5c3cc65d809f7da5e8de88afcf8562c5b48

Diff:

Revision 5 (+1284 -102)

Show changes

	docs/rbtools/_ext/rbt_commands.py
	rbtools/commands/base/commands.py
	rbtools/commands/base/options.py
	rbtools/commands/tests/test_command_initialization.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

Ship it!

```
Ship It!
```

Status:: Completed
Change Summary:: Pushed to release-5.x (b6dcc26)