Clean up configs around mergeability behavior
Gerrit now lets admins decide if they want to optimize speed of
operations by omitting 'mergeable' from the change index and ChangeInfo
in API responses. Omitting 'mergeable' from the change index also means
that Gerrit will not reindex all open changes when the target ref
advances. This operation is especially costly on repositories with a
large number of open changes.
Prior to this commit, this was controlled by the following switches:
gerrit.config:
- change.api.excludeChangeInMergeable: Skip 'mergable' in API
responses.
- index.change.indexMergeable: Skip mergeable when indexing.
ListChangeOptions:
- SKIP_MERGEABLE: Skip 'mergeable' on-demand in the query at hand.
These three knobs make it hard to get this right. In addition, they
allow for potentially dangerous behavior when
change.api.excludeChangeInMergeable=false and
index.change.indexMergeable=false since this forces Gerrit to recompute
the 'mergeability' bit potentially many times when returning query
responses.
This commit cleans up this landscape by deprecating the SKIP_MERGEABLE
change list option. The idea is that Gerrit admins need to be
prescriptive about the performance behavior of their systems. So the
behavior should be controlled system-wide instead of per-request.
The two Gerrit configs are unified into an enum that allows us to get
rid of the dangerous behavior. The possible states of
change.mergeabilityComputationBehavior are:
- API_REF_UPDATED_AND_CHANGE_REINDEX
- REF_UPDATED_AND_CHANGE_REINDEX
- NEVER
Change-Id: I01c87f6f6d731121b51301f403fa92de3e4c72f7
diff --git a/Documentation/config-gerrit.txt b/Documentation/config-gerrit.txt
index fc4b00a..bc3d38c 100644
--- a/Documentation/config-gerrit.txt
+++ b/Documentation/config-gerrit.txt
@@ -1171,15 +1171,6 @@
+
Default is `ALL`.
-[[change.api.excludeMergeableInChangeInfo]]change.api.excludeMergeableInChangeInfo::
-+
-If true, the mergeability bit in
-link:rest-api-changes.html#change-info[ChangeInfo] will never be set. It can
-be requested separately through the
-link:rest-api-changes.html#get-mergeable[get-mergeable] endpoint.
-+
-Default is false.
-
[[change.cacheAutomerge]]change.cacheAutomerge::
+
When reviewing diff commits, the left-hand side shows the output of the
@@ -1232,6 +1223,34 @@
By default 1000.
+[[change.mergeabilityComputationBehavior]]change.mergeabilityComputationBehavior::
++
+This setting determines when Gerrit computes if a change is mergeable or not.
+This computation is expensive, especially when the repository is large or when
+there are many open changes.
++
+This config can have the following states:
++
+* `API_REF_UPDATED_AND_CHANGE_REINDEX`: Gerrit indexes `mergeability` enabling
+ the `is:mergeable` predicate in change search and allowing fast retrieval of
+ this bit in query responses. Gerrit will always serve `mergeable` in
+ link:rest-api-changes.html#change-info[ChangeInfo] objects.
+ Gerrit will reindex all open changes when the target ref advances (expensive).
+* `REF_UPDATED_AND_CHANGE_REINDEX`: Gerrit indexes `mergeability` enabling the
+ `is:mergeable` predicate in change search and allowing fast retrieval of this
+ bit in query responses. Gerrit will never serve `mergeable` in
+ link:rest-api-changes.html#change-info[ChangeInfo]
+ objects. This state can be a final state for instances that only want to
+ optimize the read path, but not the write path for speed or serve as an
+ intermediary step for instances that want to optimize both and need to migrate
+ callers of their API.
+ Gerrit will reindex all open changes when the target ref advances (expensive).
+* `NEVER`: Gerrit does not index `mergeable`, so `is:mergeable` is disabled as
+ query operator. Gerrit does not serve `mergeable` in
+ link:rest-api-changes.html#change-info[ChangeInfo].
+
+Default is `REF_UPDATED_AND_CHANGE_REINDEX`.
+
[[change.move]]change.move::
+
Whether the link:rest-api-changes.html#move-change[Move Change] REST
@@ -1400,9 +1419,10 @@
+
By default `true`, meaning mergeable changes are auto-abandoned.
+
-If link:#index.change.indexMergeable[`index.change.indexMergeable`]
-is disabled, setting this option to `false` has no effect and it
-behaves as though it were set to `true`.
+If
+link:#change.mergeabilityComputationBehavior[`change.mergeabilityComputationBehavior`]
+is set to `NEVER`, setting this option to `false` has no effect and it behaves
+as though it were set to `true`.
[[changeCleanup.cleanupAccountPatchReview]]changeCleanup.cleanupAccountPatchReview::
+
@@ -2776,22 +2796,6 @@
If not set or set to a zero, defaults to the number of logical CPUs as returned
by the JVM. If set to a negative value, defaults to a direct executor.
-[[index.change.indexMergeable]]index.change.indexMergeable::
-+
-Specifies if `mergeable` should be index or not. Indexing this field enables
-queries that contain the mergeability operator (`is:mergeable`). If enabled,
-Gerrit will check if the change is mergeable into the target branch when
-reindexing a change. This is an expensive operation.
-+
-If true, Gerrit will reindex all open changes when the target ref advances.
-Depending on the frequency of updates to the ref and the number of open changes,
-this can be very expensive.
-+
-When this setting is changed from `false` to `true`, all changes need to be
-reindexed.
-+
-Defaults to true.
-
[[index.onlineUpgrade]]index.onlineUpgrade::
+
Whether to upgrade to new index schema versions while the server is
@@ -3102,7 +3106,7 @@
events.
+
This can be set to the set of minimal options that consumers of Gerrit's
-events need. A minimal set would be (`SKIP_MERGEABLE`,`SKIP_DIFFSTAT`).
+events need. A minimal set would be (`SKIP_DIFFSTAT`).
+
Every option that gets added here will have a performance impact. The
general recommendation is therefore to set this to a minimal set of
