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

 






 

 


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

 




















 

  

   Information

  





 
 

  maubin
 









 
 

  RBTools
 









 
 

  release-5.x
 









 
 

  
 









 
 

  
 






 




 

  

   Reviewers

  





 
 

  rbtools
 









 
 

  
 






 








 





  


 
 

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

     


    		
    ba2deda4598c0829cb6c26618cdfa952949257d2

   



  
 




 













 






 
 
 

  

   

    

     
    

    
    
     
  • 
      
     
    • 
     
  • 
      
     
    • 
     
  • 
      
     
    • 
     
  • 
      
     
    • 
     
  • 
      
     
    • 
    

   

   

    
     

      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




   

   







  

 



 

  


   

   

    
 
david



    
   


  

  

  



    




  1. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    2. 

















  2. 
 
    
  
  
    
  
 
    
  
    
   
    
    
     
    
      
       rbtools/commands/base/commands.py
       


        (Diff revision 1)


       
      
     
    
        
    
     
     
    

     
     
    

     
     
    

        
   
    
  
    
 
    

   
    
    
    




    
 
    
  
  
  

  
  
   Show all issues
  
 
    

    



    
    Can we add a blank line above this?
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    3. 






  3. 
 
    
  
  
    
  
 
    
  
    
   
    
    
     
    
      
       rbtools/commands/base/options.py
       


        (Diff revision 1)


       
      
     
    
        
    
     
     
    

     
     
    

        
   
    
  
    
 
    

   
    
    
    




    
 
    
  
  
  

  
  
   Show all issues
  
 
    

    



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

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    4. 




  4. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    5. 




  

 
















 



 

  

   




maubin




   

   

  

 



 















 





 

  

   




david




   

   









  

 



 

  


   

   

    
 
david



    
   


  

  

  



    




  1. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    2. 

















  2. 
 
    
  
  
    
  
 
    
  
    
   
    
    
     
    
      
       rbtools/commands/base/options.py
       


        (Diff revisions 1 - 2)


       
      
     
    
        
    
     
     
    

     
     
    

        
   
    
  
    
 
    

   
    
    
    




    
 
    
  
  
  

  
  
   Show all issues
  
 
    

    



    
    This should come from collections.abc instead of typing
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    3. 




  3. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    4. 




  

 
















 



 

  

   




maubin




   

   

  

 



 















 





 

  

   




david




   

   







  

 



 

  


   

   

    
 
david



    
   


  

  

  



    




  1. 
 
    
  
    
   
    Ship It!
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

    2. 















  2. 
 
    
  
    
   
    
  
    
 
    

 
    
  


    
 
    
 
      

  

 
    


    

 
    

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

     


    		
    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.