Summary

Add a guide for writing custom review request conditions.

Review Request #15071 — Created May 21, 2026 and submitted May 26, 2026, 4:11 a.m.

Information

Owner

chipx86

Repository

Review Board

Branch

release-8.x

Bugs

Depends On

Reviewers

Groups

reviewboard

People

Description

This is a complete guide for writing custom review request conditions,
used for integrations and in the future other parts of the UI.

It starts off with an education of what conditions are for and the main
components, and then walks through the types of condition choices and
customization options, the operators and customization for those, and
then working with value fields, followed by how to register condition
choices.

Testing Done

Built the docs. Checked for any obvious build or spelling errors.

Ran it through Claude to check for any code or writing issues.

Commits

Summary	ID
Add a guide for writing custom review request conditions. This is a complete guide for writing custom review request conditions, used for integrations and in the future other parts of the UI. It starts off with an education of what conditions are for and the main components, and then walks through the types of condition choices and customization options, the operators and customization for those, and then working with value fields, followed by how to register condition choices.	833c3ed033435cd655a7b08e6f4486ba9265a4fd

Summary

Add a guide for writing custom review request conditions.

This is a complete guide for writing custom review request conditions, used for integrations and in the future other parts of the UI. It starts off with an education of what conditions are for and the main components, and then walks through the types of condition choices and customization options, the operators and customization for those, and then working with value fields, followed by how to register condition choices.

833c3ed033435cd655a7b08e6f4486ba9265a4fd

Issues

Description	From	Last Updated
Typo: trying to matching -> trying to match	david	May 25, 2026, 10:06 p.m.
I notice in other examples, you got rid of the gettext wrapping.	maubin	May 25, 2026, 10:05 p.m.
This is missing a : Also, other similar lists in this doc are using paragraph mode (blank line between term …	david	May 25, 2026, 10:06 p.m.
We haven't seen this before, we see it below.	maubin	May 25, 2026, 10:05 p.m.
Can we put in a type hint for the generic here too (like we do in review-request-condition-choices-hook.rst) ?	david	May 25, 2026, 10:06 p.m.
Wrapping is a little funky here.	david	May 26, 2026, 2:01 a.m.
These are actually the same as Any/None, just renamed in this class. We should get rid of this line.	david	May 26, 2026, 2:02 a.m.
This should be in an if TYPE_CHECKING block. Same for other examples in this change.	david	May 26, 2026, 3:42 a.m.
One too many ===s here	david	May 26, 2026, 2:03 a.m.

flake8 passed.

JSHint passed.

docs/manual/extending/extensions/condition-choices.rst (Diff revision 1)

The issue has been resolved. Show all issues

I notice in other examples, you got rid of the gettext wrapping.

chipx86

May 25, 2026, 10:13 p.m.

Yeah, for got to nuke these ones. It's because extensions, even if they use gettext, can't really add to our localizations.

docs/manual/extending/extensions/condition-choices.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
We haven't seen this before, we see it below.
```
1. chipx86
  
  May 25, 2026, 10:13 p.m.
  Ah good catch. Fallout from moving sections around.

docs/manual/extending/extensions/condition-choices.rst (Diff revision 1)
The issue has been resolved. Show all issues
```
Typo: trying to matching -> trying to match
```

docs/manual/extending/extensions/condition-choices.rst (Diff revision 1)

The issue has been resolved. Show all issues

This is missing a :

Also, other similar lists in this doc are using paragraph mode (blank line between term and definition). We might want to do that here.

docs/manual/extending/extensions/condition-choices.rst (Diff revision 1)

The issue has been resolved. Show all issues

Can we put in a type hint for the generic here too (like we do in review-request-condition-choices-hook.rst) ?

Change Summary:


Removed gettext usage from a code sample.
Changed the ConditionValue class list to use paragraph mode.
Added a generic for ConditionValueMultipleChoiceField, and documented it with a link to Python generics.
Fixed a reference to point further below.
Fixed typos.

Commits:

	Summary	ID
	Add a guide for writing custom review request conditions. This is a complete guide for writing custom review request conditions, used for integrations and in the future other parts of the UI. It starts off with an education of what conditions are for and the main components, and then walks through the types of condition choices and customization options, the operators and customization for those, and then working with value fields, followed by how to register condition choices.	753ba0b93632e3bda8222becc6e98230a0220b78
	Add a guide for writing custom review request conditions. This is a complete guide for writing custom review request conditions, used for integrations and in the future other parts of the UI. It starts off with an education of what conditions are for and the main components, and then walks through the types of condition choices and customization options, the operators and customization for those, and then working with value fields, followed by how to register condition choices.	7ea1ea6e93a1897d13cf1e85ce1d9519ccdd2053

Diff:

Revision 2 (+1498 -274)

Show changes

	docs/manual/extending/index.rst
	docs/manual/extending/extensions/condition-choices.rst
	docs/manual/extending/extensions/hooks/review-request-condition-choices-hook.rst

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

docs/manual/extending/extensions/condition-choices.rst (Diff revision 2)

The issue has been resolved. Show all issues

Wrapping is a little funky here.

docs/manual/extending/extensions/condition-choices.rst (Diff revision 2)
The issue has been resolved. Show all issues
```
These are actually the same as Any/None, just renamed in this class. We should get rid of this line.
```

docs/manual/extending/extensions/condition-choices.rst (Diff revision 2)

The issue has been dropped. Show all issues

This should be in an if TYPE_CHECKING block. Same for other examples in this change.

chipx86

May 26, 2026, 2:03 a.m.

I've been erring on the side of keeping the code concise and not having to explain the TYPE_CHECKING stuff. My thought was, concise examples highlighting what we're showing off is important, and TYPE_CHECKING is something that is non-obvious and optional.

The average IT team working on an extension isn't going to be affected by importing things only used for typing from our codebase at runtime. If they don't understand TYPE_CHECKING and put something there and then end up needing it, there's going to be confusion.

The more advanced Python developer with understand all this and have their own approach to either importing as-is or importing into a TYPE_CHECKING. They won't just be copying/pasting our code whole-sale.

david

May 26, 2026, 3:42 a.m.
```
Sounds fine.
```

docs/manual/extending/extensions/condition-choices.rst (Diff revision 2)
The issue has been resolved. Show all issues
```
One too many ===s here
```

Change Summary:


Fixed wrapping.
Removed a redundant pair of operators.
Fixed the length of a === header.

Commits:

	Summary	ID
	Add a guide for writing custom review request conditions. This is a complete guide for writing custom review request conditions, used for integrations and in the future other parts of the UI. It starts off with an education of what conditions are for and the main components, and then walks through the types of condition choices and customization options, the operators and customization for those, and then working with value fields, followed by how to register condition choices.	7ea1ea6e93a1897d13cf1e85ce1d9519ccdd2053
	Add a guide for writing custom review request conditions. This is a complete guide for writing custom review request conditions, used for integrations and in the future other parts of the UI. It starts off with an education of what conditions are for and the main components, and then walks through the types of condition choices and customization options, the operators and customization for those, and then working with value fields, followed by how to register condition choices.	833c3ed033435cd655a7b08e6f4486ba9265a4fd

Diff:

Revision 3 (+1494 -274)

Show changes

	docs/manual/extending/index.rst
	docs/manual/extending/extensions/condition-choices.rst
	docs/manual/extending/extensions/hooks/review-request-condition-choices-hook.rst

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

Status:: Completed
Change Summary:: Pushed to release-8.x (f5d80d0)