Add the `rbt review` command.

Review Request #11883 — Created Nov. 24, 2021 and submitted

Information

RBTools
master

Reviewers

This change adds a new RBTools command for creating and editing reviews.
This uses the new MultiCommand subclass in order to provide a variety
of functionality within a single command:

  • rbt review edit will create or edit a draft review.
  • rbt review discard will discard a draft review.
  • rbt review publish will publish a draft review.
  • rbt review add-diff-comment will add a new diff comment.
  • rbt review add-file-attachment-comment will add a new file
    attachment comment.
  • rbt review add-general-comment will add a new general comment.

Based on work by Anahita Mohapatra at /r/11502/.

Ran through manual test cases for each of the review subcommands:
- Creating a new review with various content.
- Editing an existing draft review.
- Creating general comments (both markdown and plain)
- Creating file attachment comments (both markdown and plain)
- Creating diff comments (markdown and plain, single- and multi-line).
- Discarding a draft review.
- Publishing a draft review.
- Tested validation and error handling (file attachment IDs, diff
filenames, diff revisions)

Summary ID
Add the `rbt review` command.
This change adds a new RBTools command for creating and editing reviews. This uses the new `MultiCommand` subclass in order to provide a variety of functionality within a single command: - `rbt review edit` will create or edit a draft review. - `rbt review discard` will discard a draft review. - `rbt review publish` will publish a draft review. - `rbt review add-diff-comment` will add a new diff comment. - `rbt review add-file-attachment-comment` will add a new file attachment comment. - `rbt review add-general-comment` will add a new general comment. Based on work by Anahita Mohapatra at /r/11502/. Testing Done: Ran through manual test cases for each of the review subcommands: - Creating a new review with various content. - Editing an existing draft review. - Creating general comments (both markdown and plain) - Creating file attachment comments (both markdown and plain) - Creating diff comments (markdown and plain, single- and multi-line). - Discarding a draft review. - Publishing a draft review. - Tested validation and error handling (file attachment IDs, diff filenames, diff revisions)
73136b9fc5cee6ce3440b7e1dc973f2978b6a333
Description From Last Updated

F401 'argparse' imported but unused

reviewbotreviewbot

F401 'sys' imported but unused

reviewbotreviewbot

F401 'six' imported but unused

reviewbotreviewbot

F841 local variable 'file_attachment' is assigned to but never used

reviewbotreviewbot

F841 local variable 'e' is assigned to but never used

reviewbotreviewbot

rbt review <subcommand> --help?

chipx86chipx86

Can you add a Version Added?

chipx86chipx86

Can we give the base classes a Base prefix?

chipx86chipx86

Some of the commands do some lookups and possible CommandError raising before operating on a draft. If we do this …

chipx86chipx86

We shouldn't need to provide this. It'll be the default (and will use the correct string type).

chipx86chipx86

Typo: MARKDOMN -> MARKDOWN

chipx86chipx86

Can we end all the help_text strings with a period, like we do in Command.description and help= strings? Same applies …

chipx86chipx86

We use uppercase metavars in all options in the codebase. Can you update all the ones in the change to …

chipx86chipx86

This isn't needed.

chipx86chipx86

This should probably use default=1. I think we can then avoid checking against None below.

chipx86chipx86

Typo: "specifieud"

chipx86chipx86

We do self.options all over the place. Let's pull it out into a local variable, reduce the noise and the …

chipx86chipx86

"fid" is kind of confusing. Can we just make it "ID"?

chipx86chipx86

"id" -> "ID" I don't think we need the quotes around the ID numbers. We don't use them elsewhere.

chipx86chipx86

Missing a trailing period.

chipx86chipx86

Typo: MARKDOMN -> MARKDOWN. I state in another comment that we may want to consider a standard option we can …

chipx86chipx86

I was looking into whether we could avoid having to use two variables and the complex logic below but also …

chipx86chipx86

Missing a trailing period.

chipx86chipx86

We have this logic three times in two existing commands, and are adding more. While --markdown isn't a standard argument …

chipx86chipx86

The trailing newline isn't needed here.

chipx86chipx86

Missing a trailing period.

chipx86chipx86

Can we call this create_review_if_missing, and document it?

chipx86chipx86

This can use the new helper function, right?

chipx86chipx86
Checks run (1 failed, 1 succeeded)
flake8 failed.
JSHint passed.

flake8

david
chipx86
  1. 
      
  2. docs/rbtools/rbt/commands/review.rst (Diff revision 2)
     
     
    Show all issues

    rbt review <subcommand> --help?

  3. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    Can you add a Version Added?

  4. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    Can we give the base classes a Base prefix?

  5. rbtools/commands/review.py (Diff revision 2)
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
    Show all issues

    Some of the commands do some lookups and possible CommandError raising before operating on a draft. If we do this first, we can easily end up with empty drafts hanging around.

    How about just moving this to a get_review_draft method or something, and calling it when ready to work on the draft?

  6. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    We shouldn't need to provide this. It'll be the default (and will use the correct string type).

  7. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    Typo: MARKDOMN -> MARKDOWN

  8. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    Can we end all the help_text strings with a period, like we do in Command.description and help= strings?

    Same applies below.

  9. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    We use uppercase metavars in all options in the codebase. Can you update all the ones in the change to be uppercase?

    (Should also be one word: "FILENAME")

  10. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    This isn't needed.

  11. rbtools/commands/review.py (Diff revision 2)
     
     
     
     
     
     
    Show all issues

    This should probably use default=1. I think we can then avoid checking against None below.

  12. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    Typo: "specifieud"

  13. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    We do self.options all over the place. Let's pull it out into a local variable, reduce the noise and the repeated attribute lookups.

    Same with api_root.

    This applies to other implementations as well.

    1. api_root is used once, maybe twice per command. It doesn't seem worth it for that. Did it for options.

  14. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    "fid" is kind of confusing. Can we just make it "ID"?

  15. rbtools/commands/review.py (Diff revision 2)
     
     
     
    Show all issues

    "id" -> "ID"

    I don't think we need the quotes around the ID numbers. We don't use them elsewhere.

  16. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    Missing a trailing period.

  17. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    Typo: MARKDOMN -> MARKDOWN.

    I state in another comment that we may want to consider a standard option we can plug in for Markdown, and given the error here, maybe this is a good time to do it?

  18. rbtools/commands/review.py (Diff revision 2)
     
     
     
     
     
     
     
     
     
     
     
     
     
    Show all issues

    I was looking into whether we could avoid having to use two variables and the complex logic below but also gain the useful error message about mutual-exclusivity.

    argparse has an add_mutually_exclusive_group for this purpose, but it's probably too heavy-weight, and we don't have an Option/OptionGroup equivalent for it (though we could add it).

    Anyway, so I checked other commands, and this scenario is all over the place, and probably isn't a big deal. A --thing and --no-thing both populating the same variable is common (such as rbt land --push and --no-push), and we haven't heard of any confusion around them yet.

    So I think it'd be better to err on the side of simplicity here, have both these options use the same variable and default=None (which is the default value for default anyway), and then trust the value when making decisions below.

    If we want to add mutual-exclusive support during parsing, we should probably handle that in common code somehow.

  19. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    Missing a trailing period.

  20. rbtools/commands/review.py (Diff revision 2)
     
     
     
     
     
     
    Show all issues

    We have this logic three times in two existing commands, and are adding more.

    While --markdown isn't a standard argument (we should probably make a constant for it though), I think it'd be valuable to have at least a utility function that gives us a text type for a given value + capability, and just use that.

    1. I don't know that we can have a good constant for it because the help text is different in every instance. I'll add the helper though.

  21. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    The trailing newline isn't needed here.

  22. rbtools/commands/review.py (Diff revision 2)
     
     
    Show all issues

    Missing a trailing period.

  23. 
      
david
chipx86
  1. 
      
  2. rbtools/commands/review.py (Diff revision 3)
     
     
    Show all issues

    Can we call this create_review_if_missing, and document it?

  3. rbtools/commands/review.py (Diff revision 3)
     
     
     
     
     
     
    Show all issues

    This can use the new helper function, right?

  4. 
      
david
chipx86
  1. Ship It!
  2. 
      
david
Review request changed
Status:
Completed
Change Summary:
Pushed to master (7c746df)