Add Overview section in the Dashboard

Review Request #10166 — Created Sept. 22, 2018 and submitted

Information

Review Board
master
c7fc441...

Reviewers

Users have to switch between sections to view a open review requests that
they have sent out or reviews requests that are targeting them indirectly.

The dashboard now contains a new section that contains all open review
requests that the user is either a submitter of or a reviewer (either
directly or indirectly).

Testing was done by checking the Overview section in the browser to see
if the expected review requests were displayed.
Python Unit tests were run to ensure the query returns the expected review
requests.


Description From Last Updated

Usually commit messages are descriptive (e.g. what the patch does) instead of declarative (what I -- or you -- did …

brenniebrennie

Can you update your summary with the new section name?

brenniebrennie

The right caret will have to align with the "Overview" text. You'll also want to bump its font size up …

brenniebrennie

E501 line too long (81 > 79 characters)

reviewbotreviewbot

E302 expected 2 blank lines, found 1

reviewbotreviewbot

E501 line too long (100 > 79 characters)

reviewbotreviewbot

E127 continuation line over-indented for visual indent

reviewbotreviewbot

Some general things to note about evolutions, in case you need to do them in the future (or now, if …

chipx86chipx86

This is wrapped way too early. You have more room on the line for content.

chipx86chipx86

This will need to follow the modern documentation format, with a Yield section. Someone at the sprint can point you …

chipx86chipx86

We'd update this to "overview".

chipx86chipx86

Two blank lines between top-level classes/functions/groups of variables.

chipx86chipx86

These should be in alphabetical order.

chipx86chipx86

For now, let's not set this as the default view. Users can find these sorts of changes to be very …

chipx86chipx86

This needs to use our modern docstring format.

chipx86chipx86

This will need a docstring. (Many of the others are missing this, but they predate the current standards. Don't worry …

chipx86chipx86

W293 blank line contains whitespace

reviewbotreviewbot

W293 blank line contains whitespace

reviewbotreviewbot

W291 trailing whitespace

reviewbotreviewbot

W291 trailing whitespace

reviewbotreviewbot

W291 trailing whitespace

reviewbotreviewbot

W293 blank line contains whitespace

reviewbotreviewbot

W291 trailing whitespace

reviewbotreviewbot

W291 trailing whitespace

reviewbotreviewbot

This will require at least one unit test to ensure the query returns the correct review requests.

brenniebrennie

E501 line too long (87 > 79 characters)

reviewbotreviewbot

E501 line too long (99 > 79 characters)

reviewbotreviewbot

E501 line too long (99 > 79 characters)

reviewbotreviewbot

E501 line too long (81 > 79 characters)

reviewbotreviewbot

E501 line too long (81 > 79 characters)

reviewbotreviewbot

We avoid inline styles as much as possible. Instead, can you put a class on this (maybe overview-section-row) and add …

brenniebrennie

The other docstrings quote the section name, e.g. The "Overview" section ...

brenniebrennie

Since you're updating this, can you update this to our documentation style? Also, technically, for reStructuredText, this list is mis-formatted …

brenniebrennie

The summary should be on the first line and should fit on a single line.

brenniebrennie

This should be in the imperitive mood, as if it were a command (i.e., "Return" instead of "Returns").

brenniebrennie

This should be formatted as :py:meth:`ReviewRequest.objects.public <reviewboard.reviews.managers.ReviewRequestManager.public>` which will format it as a method invocation and link to the correct …

brenniebrennie

This is actually a Q (django.db.models.Q) object.

brenniebrennie

How about: A query for all review requests the users is inolved in as either a submitter or a reviewer …

brenniebrennie

i.e does not end a sentence. It is a joining clause .

brenniebrennie

The summary should be on the first line and should fit on a single line.

brenniebrennie

QuerySet

brenniebrennie

Missing a period.

brenniebrennie

The actual class name is dict

brenniebrennie

Missing a period.

brenniebrennie

Same comment re: wording as above.

brenniebrennie

Return documentation is formatted as: Returns: django.http.HttpResponse: The rendered HTTP response for the datagrid. What datagrid is rendered depends on …

brenniebrennie

this should go above args in the documentation noting that the view GET parameter is used, e.g. ```python """Display the …

brenniebrennie

E501 line too long (80 > 79 characters)

reviewbotreviewbot

Typo here: 'mine'to -> 'mine'

daviddavid

Although we often use six.text_type in the code, docs should use unicode in order to link to the right thing.

daviddavid

Typo: objectts

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

flake8

bolariinwa
Review request changed

Checks run (1 failed, 1 succeeded)

flake8 failed.
JSHint passed.

flake8

bolariinwa
chipx86
  1. You're delving into a lot of complex stuff, which is great! And you've done a great job with the change. As I've been reviewing it, though, I've been mulling over what it is we may really want to do with this sort of view, and have some thoughts.

    Take this as a proposal. I'm sure there will be differing thoughts on it.

    There's two things that stood out:

    1. The new counter is maybe not necessary, and if we can avoid it, that'd be awesome. Database changes are expensive and invasive. One seemingly simple database change can turn into hours or days of upgrade time for some customers. This one's easier to handle, but if it were on, say, ReviewRequest, we'd definitely be looking at weekend downtime. So we try not to add them unless necessary. And we only need this if we use the current design. Which is where my second thought comes in.
    2. The name "My Reviews" is not quite right for what this is. First, these are review requests, not reviews. Second, they're not all "mine." I know the original project name is "My Reviews," but we can do better, and be less confusing to users. Along with this, the "All" item underneath it is inconsistently named, as "All" in "Outgoing" means "Even ones that are closed." There's only a single item in here, though, which is maybe not necessary.

    I think we can address both of these by making two changes:

    1. Renaming "My Reviews" to "Overview".
    2. Getting rid of the "All" item, and instead folding that into "Overview".

    I don't think we even need a counter for this. It can just be "Overview." Let the finger-grained sections below supply the counters. They're more useful that way, and it frees us up to do things with this section later (I have some pie-in-the-sky ideas for showing more useful information than just a list of review requests down the road, which would make a counter less relevant anyway -- backburner idea for something I call "Radar," but that's a longer discussion.)

    This would look something like:

    Image

    This would massively simplify the change, though you would need to allow sections to be selectable/made active, so there's some new work there. The counter work could be tossed, reducing the amount of unit tests and query consolidation I was going to have you write (counters are complex), and we'd have something that we could land pretty quickly.

    With that in mind, I'm going to drop a bunch of comments I had for the counters. If it turns out that you're going to end up having to add them anyway, I'll have a bunch of comments in a separate review.

    1. (Ignore the "Submitted" entries in that screenshot. All I did was mess with the sidebar and the header in my local browser.)

      (Also sorry for the huge screenshot. Good EasyFix bug: Set the CSS for images in comments to be max-width: 100%; height: auto;)

    2. Another thought is that, in order to indicate that Overview is even clickable, we could put a little ">" arrow icon where the counter would normally be, helping to show that there's something that happens when you click on it.

    3. Would the ">" icon be an img or just text?

    4. We use Font Awesome for a lot of basic icons. You can do <span class="fa fa-caret-right"></span> and get a little right arrow that should look alright.

  2. Some general things to note about evolutions, in case you need to do them in the future (or now, if we have to keep this counter):

    1. The name of the evolution should describe the model schema changes, not the reason you're making the model changes. When adding fields, this is gneerally going to include the model name and field name. For instance, localsiteprofile_total_request_count.
    2. This needs to use underscores, not hyphens.
    3. Last item in a list should always have a trailing comma, so this line doesn't have to be modified next time we add an entry.
  3. reviewboard/datagrids/builtin_items.py (Diff revision 3)
     
     
     
     
     

    This is wrapped way too early. You have more room on the line for content.

  4. reviewboard/datagrids/builtin_items.py (Diff revision 3)
     
     

    This will need to follow the modern documentation format, with a Yield section. Someone at the sprint can point you to the docs for this.

    1. I believe chipx86 meant to say Yields: instead of Yield:.

  5. reviewboard/datagrids/builtin_items.py (Diff revision 3)
     
     

    We'd update this to "overview".

  6. reviewboard/datagrids/builtin_items.py (Diff revision 3)
     
     
     
     

    Two blank lines between top-level classes/functions/groups of variables.

  7. reviewboard/datagrids/grids.py (Diff revision 3)
     
     
     

    These should be in alphabetical order.

  8. reviewboard/datagrids/grids.py (Diff revision 3)
     
     

    For now, let's not set this as the default view. Users can find these sorts of changes to be very disruptive, which means us fielding a lot of support requests :) For now, let's keep the existing default view, and make the new Overview an optional thing users can go to. They can always bookmark it if they want.

  9. reviewboard/reviews/managers.py (Diff revision 3)
     
     
     
     
     
     
     
     
     
     

    This needs to use our modern docstring format.

  10. reviewboard/reviews/managers.py (Diff revision 3)
     
     

    This will need a docstring. (Many of the others are missing this, but they predate the current standards. Don't worry about those, but provide one here.)

    I'd also like this to be called to_or_from_user.

  11. 
      
bolariinwa
Review request changed

Change Summary:

Resolved a few issues

Commit:

-08b255c72cdf33e0dc866136322bf2bf6d9f4235
+cd63b5f372b6c1664468db8c7b7b517dd1672314

Diff:

Revision 4 (+38)

Show changes

Checks run (1 failed, 1 succeeded)

flake8 failed.
JSHint passed.

flake8

bolariinwa
bolariinwa
bolariinwa
Review request changed

Change Summary:

Improved documentation using the modern documentation format

Commit:

-eb76ccd6260ca673733e360eddb8ac5f498f0874
+011413e77331f5d1b3e8e8bfbc414ae28c3e8eff

Diff:

Revision 6 (+70)

Show changes

Checks run (1 failed, 1 succeeded)

flake8 failed.
JSHint passed.

flake8

bolariinwa
bolariinwa
brennie
  1. 
      
  2. Usually commit messages are descriptive (e.g. what the patch does) instead of declarative (what I -- or you -- did to write the patch).

    e.g., for your second paragraph:

    The dashboard now contains a new section that contains all review
    requests that the user is either a submitter of or a reviewer (either
    directly or indirectly).
    
  3. Can you update your summary with the new section name?

  4. reviewboard/reviews/managers.py (Diff revision 8)
     
     

    This will require at least one unit test to ensure the query returns the correct review requests.

  5. 
      
brennie
  1. 
      
  2. The right caret will have to align with the "Overview" text. You'll also want to bump its font size up (try 200%?)

    You might want to try the following:

    • Wrap the Overview and caret in a <span>/<div> and style it with line-height: normal
    • Wrap and style it with vertical-align: middle.

    If neither of these work, we can help you figure out the appropriate styles.

  3. 
      
bolariinwa
Review request changed

Summary:

-Add new 'My Reviews' section in the Dashboard
+Add Overview section in the Dashboard

Description:

~  

Users have to switch between views to view a summary on review requests

~   that they have sent out or reviews requests that are targeting them
  ~

Users have to switch between sections to view a open review requests that

  ~ they have sent out or reviews requests that are targeting them indirectly.

-   indirectly.

   
~  

I added a new section to the dashboard with a link that allows users to

~   view review requests that they sent out and review requests that
~   indirectly target them.

  ~

The dashboard now contains a new section that contains all open review

  ~ requests that the user is either a submitter of or a reviewer (either
  ~ directly or indirectly).

Testing Done:

~  

Testing was done by checking the new 'My Review' section in the browser.

  ~

Testing was done by checking the Overview section in the browser to see

  + if the expected review requests were displayed.
  + Python Unit tests were run to ensure the query returns the expected review
  + requests.

Commit:

-26f53f850320d1822790df6d818cb6b1d8720cbf
+3b6ccd4050c08a88d0834b1de09cead3431086fe

Diff:

Revision 9 (+173)

Show changes

Added Files:

Checks run (1 failed, 1 succeeded)

flake8 failed.
JSHint passed.

flake8

bolariinwa
Review request changed

Checks run (1 failed, 1 succeeded)

flake8 failed.
JSHint passed.

flake8

bolariinwa
brennie
  1. Just one more minor thing!

  2. We avoid inline styles as much as possible. Instead, can you put a class on this (maybe overview-section-row) and add the styling to a LESS file?

    It should probably go in static/rb/css/ui/sidebars.less.

  3. 
      
bolariinwa
bolariinwa
brennie
  1. You'll notice these comments are pretty nitty-gritty, which means this is getting very close to a ship it and we're just working on polish!

  2. reviewboard/datagrids/builtin_items.py (Diff revision 12)
     
     

    The other docstrings quote the section name, e.g.

    The "Overview" section ...
    
  3. reviewboard/datagrids/views.py (Diff revision 12)
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     

    Since you're updating this, can you update this to our documentation style?

    Also, technically, for reStructuredText, this list is mis-formatted (not your fault); instead the * should be in the same column as the V in Valid ....

  4. reviewboard/reviews/managers.py (Diff revision 12)
     
     

    The summary should be on the first line and should fit on a single line.

  5. reviewboard/reviews/managers.py (Diff revision 12)
     
     

    This should be in the imperitive mood, as if it were a command (i.e., "Return" instead of "Returns").

  6. reviewboard/reviews/managers.py (Diff revision 12)
     
     

    This should be formatted as

    :py:meth:`ReviewRequest.objects.public <reviewboard.reviews.managers.ReviewRequestManager.public>`
    

    which will format it as a method invocation and link to the correct place in the docs.

  7. reviewboard/reviews/managers.py (Diff revision 12)
     
     

    This is actually a Q (django.db.models.Q) object.

  8. reviewboard/reviews/managers.py (Diff revision 12)
     
     
     
     
     
     

    How about:

    A query for all review requests the users is inolved 
    in as either a submitter or a reviewer (either directly
    assigned or indirectly as a member of a group).
    
  9. reviewboard/reviews/managers.py (Diff revision 12)
     
     

    i.e does not end a sentence. It is a joining clause .

  10. reviewboard/reviews/managers.py (Diff revision 12)
     
     

    The summary should be on the first line and should fit on a single line.

  11. reviewboard/reviews/managers.py (Diff revision 12)
     
     

    QuerySet

  12. reviewboard/reviews/managers.py (Diff revision 12)
     
     

    Missing a period.

  13. reviewboard/reviews/managers.py (Diff revision 12)
     
     

    The actual class name is dict

  14. reviewboard/reviews/managers.py (Diff revision 12)
     
     

    Missing a period.

  15. reviewboard/reviews/managers.py (Diff revision 12)
     
     
     
     
     
     

    Same comment re: wording as above.

  16. 
      
bolariinwa
bolariinwa
bolariinwa
brennie
  1. 
      
  2. reviewboard/datagrids/views.py (Diff revision 15)
     
     
     

    Return documentation is formatted as:

    Returns:
        django.http.HttpResponse:
        The rendered HTTP response for the datagrid. What datagrid is rendered
        depends on the ``view`` parameter.
    
  3. reviewboard/datagrids/views.py (Diff revision 15)
     
     
     
     
     
     
     
     
     
     

    this should go above args in the documentation noting that the view GET parameter is used, e.g.

    ```python
    """Display the dashboard.

    This shows review requests organized by a variety of lists, depending on the view GET parameter. Valid values of view are:

    • outgoing
    • to-me
    • ...

    Args:
    ....

    Returns:
    ...
    """

    1. For the documentation should I wrap GET and view in `` ``?
  4. 
      
bolariinwa
Review request changed

Checks run (1 failed, 1 succeeded)

flake8 failed.
JSHint passed.

flake8

bolariinwa
brennie
  1. Looks good to me! Just need another sign-off on it before landing.

  2. 
      
david
  1. 
      
  2. reviewboard/datagrids/views.py (Diff revision 17)
     
     

    Typo here: 'mine'to -> 'mine'

  3. reviewboard/datagrids/views.py (Diff revision 17)
     
     

    Although we often use six.text_type in the code, docs should use unicode in order to link to the right thing.

  4. 
      
bolariinwa
bolariinwa
bolariinwa
david
  1. Ship It!
  2. 
      
bolariinwa
Review request changed

Status: Closed (submitted)

Change Summary:

Pushed to release-4.0.x (607d101)
Loading...