config-submit-requirements.txt: Mention that 500 ISE may be returned for errors

There is a setting in gerrit.config that makes Gerrit return a '500
internal server' error instead of returning the submit requirement with
an ERROR status. Add a note to inform about this.

Release-Notes: skip
Bug: Issue b/312890385
Change-Id: I2554d03415d70f48066705b5ba3db060bd668d67
Signed-off-by: Edwin Kempin <ekempin@google.com>

Documentation/config-gerrit.txt

diff --git a/Documentation/config-gerrit.txt b/Documentation/config-gerrit.txt
index 5d37503..8e36550 100644
--- a/Documentation/config-gerrit.txt
+++ b/Documentation/config-gerrit.txt
@@ -1566,18 +1566,32 @@
 
 [[change.propagateSubmitRequirementErrors]]change.propagateSubmitRequirementErrors::
 +
-If a SubmitRequirement evaluation for a given change results in an
-ERROR status, abort the REST response with an HTTP 500 error.
+If set, requests that access the submit requirements of a change fail with an
+HTTP 500 error if the change has a submit requirement with a non-parseable
+expression that would otherwise result in an
+link:config-submit-requirements#status-error[ERROR] status for the submit
+requirement.
 +
-The ERROR status can occur if a SubmitRequirement uses a
-plugin-provided predicate (and the plugin is not available), due to
-bugs, or due to bypassing the validation that normally happens when
-updating `refs/meta/config`.
+Submit requirement expressions can become non-parseable due to bypassing the
+validation that normally happens when updating the project configuration in
+the `refs/meta/config` branch, or due to bugs in Gerrit.
 +
-Enabling this flag  makes gerrit unusuable under such conditions, so
-it is generally not recommended. However, this makes the
-application-specific ERROR status into a generic HTTP error, and can
-thus be acted on by automated deployment and monitoring infrastructure.
+A special case are expressions that use plugin-provided predicates. If any
+plugin that provides a predicate fails to load (e.g. due to an error in the
+plugin) the predicate can no longer be resolved and expressions that are using
+it can no longer be parsed. This is an error that requires the attention of the
+team that operates Gerrit, but in order to get notified when this happens the
+operation team would need to setup custom monitoring that observes whether
+link:config-submit-requirements#status-error[ERROR] statuses are returned for
+submit requirements. Instead this config option can be used to make
+non-parseable submit requirement expressions cause HTTP 500 errors which
+triggers the automatic alerting for errors that Gerrit operation teams usually
+have in place. This allows the operation team to react quickly when this
+happens.
++
+The drawback of enabling this option is that it causes requests to fail rather
+than handling parsing errors gracefully, which can make Gerrit for impacted
+users unusable.
 
 [[change.robotCommentSizeLimit]]change.robotCommentSizeLimit::
 +

Documentation/config-submit-requirements.txt

diff --git a/Documentation/config-submit-requirements.txt b/Documentation/config-submit-requirements.txt
index 48f084a..a3dfd6a 100644
--- a/Documentation/config-submit-requirements.txt
+++ b/Documentation/config-submit-requirements.txt
@@ -182,7 +182,14 @@
 link:#submit_requirement_applicable_if[applicableIf],
 link:#submit_requirement_submittable_if[submittableIf] or
 link:#submit_requirement_override_if[overrideIf] expressions resulted in an
-error.
+error, i.e. because the expression is not parseable.
+
+[NOTE]
+Gerrit can be configured to return a `500 internal server error` response
+instead of setting the status to `ERROR` (see the
+link:config-gerrit.html#change.propagateSubmitRequirementErrors[
+change.propagateSubmitRequirementErrors] option that can be set in
+`gerrit.config`).
 
 [[submit-requirement-subsection]]
 == submit-requirement subsection