Summary

Rework the ReviewRequestApprovalHook docs for better flow and guidance.

Review Request #14757 — Created Jan. 1, 2026 and updated Jan. 6, 2026, 8:49 a.m.

Information

Owner

chipx86

Repository

Review Board

Branch

release-7.1.x

Bugs

Depends On

Reviewers

Groups

reviewboard

People

Description

The ReviewRequestApprovalHook docs were pretty old and did little to
communicate the expectations of the hook. The very first sentence said
these were new in Review Board 2.0.

This change reworks the docs to clearly describe what approval state is
for and where it's used, the execution and chaining model of these
hooks, the signature of is_approved() methods, examples, and best
practices.

Typing and docs for the affected codepaths have been updated as well to
reflect what's shown in the guide and to link back to it.

Testing Done

Built the docs and checked the references/links on all affected code.

Ran content through ChatGPT for analysis and suggestions.

Commits

Summary	ID
Rework the ReviewRequestApprovalHook docs for better flow and guidance. The `ReviewRequestApprovalHook` docs were pretty old and did little to communicate the expectations of the hook. The very first sentence said these were new in Review Board 2.0. This change reworks the docs to clearly describe what approval state is for and where it's used, the execution and chaining model of these hooks, the signature of `is_approved()` methods, examples, and best practices. Typing and docs for the affected codepaths have been updated as well to reflect what's shown in the guide and to link back to it.	9552ba8a5d3f866120211119e82c8d7660bbc0b2

Summary

Rework the ReviewRequestApprovalHook docs for better flow and guidance.

The `ReviewRequestApprovalHook` docs were pretty old and did little to communicate the expectations of the hook. The very first sentence said these were new in Review Board 2.0. This change reworks the docs to clearly describe what approval state is for and where it's used, the execution and chaining model of these hooks, the signature of `is_approved()` methods, examples, and best practices. Typing and docs for the affected codepaths have been updated as well to reflect what's shown in the guide and to link back to it.

9552ba8a5d3f866120211119e82c8d7660bbc0b2

Issues

Description	From	Last Updated
This reads a little bit awkward. The review request isn't a user, the review request author (or submitter) is a …	david	Jan. 6, 2026, 12:52 a.m.
Based on the docstring, this should be bool \| tuple[bool, str \| None] (str -> bool)	david	Jan. 6, 2026, 12:53 a.m.

flake8 passed.

JSHint passed.

docs/manual/extending/extensions/hooks/review-request-approval-hook.rst (Diff revision 1)

The issue has been resolved. Show all issues

This reads a little bit awkward. The review request isn't a user, the review request author (or submitter) is a user.

reviewboard/extensions/hooks/review_request_approval.py (Diff revision 1)
The issue has been resolved. Show all issues
```
Based on the docstring, this should be bool | tuple[bool, str | None] (str -> bool)
```

Change Summary:


Fixed an awkwardly-worded comment in an example.
Fixed a bad return type in the hook.

Commits:

	Summary	ID
	Rework the ReviewRequestApprovalHook docs for better flow and guidance. The `ReviewRequestApprovalHook` docs were pretty old and did little to communicate the expectations of the hook. The very first sentence said these were new in Review Board 2.0. This change reworks the docs to clearly describe what approval state is for and where it's used, the execution and chaining model of these hooks, the signature of `is_approved()` methods, examples, and best practices. Typing and docs for the affected codepaths have been updated as well to reflect what's shown in the guide and to link back to it.	e16867a5bb3c4853e5f204d8fe9a5ae373120e8e
	Rework the ReviewRequestApprovalHook docs for better flow and guidance. The `ReviewRequestApprovalHook` docs were pretty old and did little to communicate the expectations of the hook. The very first sentence said these were new in Review Board 2.0. This change reworks the docs to clearly describe what approval state is for and where it's used, the execution and chaining model of these hooks, the signature of `is_approved()` methods, examples, and best practices. Typing and docs for the affected codepaths have been updated as well to reflect what's shown in the guide and to link back to it.	9552ba8a5d3f866120211119e82c8d7660bbc0b2

Diff:

Revision 2 (+428 -82)

Show changes

	docs/manual/extending/extensions/hooks/review-request-approval-hook.rst
	docs/manual/users/reviews/reviews.rst
	reviewboard/extensions/hooks/review_request_approval.py
	reviewboard/reviews/models/review_request.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```