Checks run (2 succeeded)
flake8
passed.
JSHint
passed.
Add documentation for User Roles.
Review Request #15068 — Created May 20, 2026 and submitted
This adds documentation for User Roles. While this is a Power Pack feature,
moving forward we'll be consolidating Power Pack documentation into the
Review Board docs base. This follows our plans of unifying things under
just one "product" and will make things easier to find for users.Along with the user roles documentation, this adds a "Useful Data and
Resources" section to the review request approval hook docs that lists
some attributes and resources that are useful for approval hooks. I added
this because I thought it'd be a good place to plug user roles.We also now allow references to the Power Pack docs.
- Built the docs and viewed them.
- Was able to click on the
UserRole.objects.for_user()reference
and get redirected to the Power Pack coderef entry for it.
| Summary | ID |
|---|---|
| 18041b17001412427bf7c34dfea9050222666d16 |
| Description | From | Last Updated |
|---|---|---|
|
We have some odd rendering for definition lists, like these. We need to fix those up, but I started to … |
chipx86
|
|
|
We have a "slug" :term: we can use to reference this, which will show what characters are allowed. Might also … |
chipx86
|
|
|
Maybe instead of "Only licensed Power Pack users," we should say "Only users assigned to your license for Review Board … |
chipx86
|
|
|
I love this example. I wonder if instead of having the code here, we should put this in the hook … |
chipx86
|
|
|
Just for correctness, this should probably be UserRole.objects.get(slug='team-lead', local_site=review_request.local_site) |
david
|
|
|
This should be UserRole.objects.for_user. We probably should also mention passing in request here (to get the local site when present) |
david
|
|
|
These headings should probably be promoted one level (i.e. "Useful Data and Resources" should be a sibling of "Common Patterns") |
david
|
|
|
Two blank lines here. |
chipx86
|
|
|
Can we make these bullet points as well? Also, each of these can be a :py:attr: or similar. |
chipx86
|
|
|
Here too. |
david
|
|
|
Let's give this an explicit title, in case the title ever changes. |
chipx86
|
|
|
"Two" here seems like it might get out of date without us noticing. Can we say "The following conditions are … |
david
|
|
|
There's an extra space in here that I think is actually likely to break the reference entirely. |
david
|
|
|
These won't link properly. We should use: * :py:attr:`~reviewboard.reviews.models.ReviewRequest.submitter` |
david
|
|
|
Extra blank line here. |
david
|
|
|
Based on feedback from David, I removed the period in mine. Trivial change. |
chipx86
|
-
-
Just for correctness, this should probably be
UserRole.objects.get(slug='team-lead', local_site=review_request.local_site) -
This should be
UserRole.objects.for_user.We probably should also mention passing in
requesthere (to get the local site when present) -
These headings should probably be promoted one level (i.e. "Useful Data and Resources" should be a sibling of "Common Patterns")
-
Review request changed
- Change Summary:
-
- Responded to feedback.
- Allow references to the Power Pack docs.
- Link to the UserRoleManager.for_user() coderef in Power Pack.
- Description:
-
This adds documentation for User Roles. While this is a Power Pack feature,
moving forward we'll be consolidating Power Pack documentation into the Review Board docs base. This follows our plans of unifying things under just one "product" and will make things easier to find for users. Along with the user roles documentation, this adds a "Useful Data and
Resources" section to the review request approval hook docs that lists some attributes and resources that are useful for approval hooks. I added this because I thought it'd be a good place to plug user roles. + + We also now allow references to the Power Pack docs.
- Testing Done:
-
~ Built the docs and viewed them.
~ - Built the docs and viewed them.
+ - Was able to click on the
UserRole.objects.for_user()reference
and get redirected to the Power Pack coderef entry for it.
- Commits:
-
Summary ID 31d4e0e9e2a24fb8649dd08714af39465263ca75 c31109ccbf1c07032e2eba5bc978f718446ae1de
Checks run (2 succeeded)
flake8
passed.
JSHint
passed.
-
-
We have some odd rendering for definition lists, like these. We need to fix those up, but I started to rethink lists like these, and have been moving to bullet points like:
* :guilabel:`...` description...This has ended up looking a bit better all around, I think. Clearly indicates these are entries in a list, and aligns the names with the descriptions. See what you think.
-
We have a "slug"
:term:we can use to reference this, which will show what characters are allowed.Might also be worth just duplicating those characters here as well.
-
Maybe instead of "Only licensed Power Pack users," we should say "Only users assigned to your license for Review Board or Power Pack ..."
We really still need some central docs in RB for the licensing that we can link to... Not going to make it for Tuesday.
-
I love this example. I wonder if instead of having the code here, we should put this in the hook docs for this and reference it. Admins should be made aware of this ability but probably aren't going to understand the code off-hand.
Ieally we'd have a full-on guide for approval hooks with different examples, but that's a larger task, and this would be more than suitable as a section under the hood.
-
-
-
Review request changed
- Commits:
-
Summary ID c31109ccbf1c07032e2eba5bc978f718446ae1de c711c71f201d5ec0a41434bb221f35494a7e0910
Checks run (2 succeeded)
flake8
passed.
JSHint
passed.
Review request changed
- Change Summary:
-
Forgot to update the paid feature admonition.
- Commits:
-
Summary ID c711c71f201d5ec0a41434bb221f35494a7e0910 573533bc15878597c9aee9fe83707027a8f174f7
Checks run (2 succeeded)
flake8
passed.
JSHint
passed.