Summary

Rework the ReviewRequestApprovalHook docs for better flow and guidance.

Review Request #14757 — Created Jan. 1, 2026 and submitted March 18, 2026, 11:13 p.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.	b54c07f84ae72a7a9f244a934b4d621c96577894

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.

b54c07f84ae72a7a9f244a934b4d621c96577894

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.
Here we could add "... pre-receive hooks (for example git-hook-check-approval)"	maubin	March 9, 2026, 11:13 p.m.
Can we link to relevant docs for any of these items?	maubin	March 3, 2026, 12:33 p.m.
This seems slightly more indented than it should be.	david	March 9, 2026, 11:14 p.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!
```

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

The issue has been resolved. Show all issues

Can we link to relevant docs for any of these items?

chipx86 March 3, 2026, 12:33 p.m.

I don't know that we have anything other than extensions and integrations. I'll link those, and if I'm missing something, let me know.

Change Summary:

Added links to the Extensions and Integrations page when listing some places where this hook is useful.

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
	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.	8b0ae7ee71e872a72f6bd6a9281c1bf1ceb20eb6

Diff:

Revision 3 (+434 -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.

docs/manual/extending/extensions/hooks/review-request-approval-hook.rst (Diff revisions 2 - 3)
The issue has been resolved. Show all issues
```
Here we could add "... pre-receive hooks (for example git-hook-check-approval)"
```

Ship it!

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

The issue has been resolved. Show all issues

This seems slightly more indented than it should be.

Change Summary:


Added a link to the RBTools hooks.
Reduced indentation of an example.

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.	8b0ae7ee71e872a72f6bd6a9281c1bf1ceb20eb6
	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.	b54c07f84ae72a7a9f244a934b4d621c96577894

Diff:

Revision 4 (+444 -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!
```

Status:: Completed
Change Summary:: Pushed to release-7.1.x (346d711)