Document introduction of `virtual_id_number` to `ChangeInfo`upstream/stable-3.7

Note that the underscore (`_`) has been removed from the variable name
to avoid resemblance to the prefix `_` used in `_number`, which
(according to the documentation) denotes deprecation.

Follow-Up-To: I85c946ef
Bug: Issue 325309573
Release-Notes: Add `virtual_id_number` to `ChangeInfo`
Forward-Compatible: checked
Change-Id: Iddf5dee45f80f863ec8dbc113e15e9499bfee757

3 files changed, 10 insertions, 4 deletions

diff --git a/Documentation/rest-api-changes.txt b/Documentation/rest-api-changes.txt
index b9de6abd8a..720ac5f909 100644
--- a/Documentation/rest-api-changes.txt
+++ b/Documentation/rest-api-changes.txt
@@ -6730,6 +6730,12 @@ the current change index doesn't have the data.
 |`_number`            ||
 The change number. (The underscore is just a relict of a prior
 attempt to deprecate the change number.)
+|`virtual_id_number`  ||
+The virtual id number is globally unique. For local changes, it is equal to the
+`_number` attribute. For imported changes, the original `_number` is processed
+through a function designed to prevent conflicts with local change numbers.
+Note that its usage is intended solely for Gerrit's internals and UI, and
+adoption outside these scenarios is not advised.
 |`owner`              ||
 The owner of the change as an link:rest-api-accounts.html#account-info[
 AccountInfo] entity.
diff --git a/java/com/google/gerrit/extensions/common/ChangeInfo.java b/java/com/google/gerrit/extensions/common/ChangeInfo.java
index d381b685ab..75b3ef51dd 100644
--- a/java/com/google/gerrit/extensions/common/ChangeInfo.java
+++ b/java/com/google/gerrit/extensions/common/ChangeInfo.java
@@ -99,7 +99,7 @@ public class ChangeInfo {
   public Boolean containsGitConflicts;
 
   public Integer _number;
-  public Integer _virtualIdNumber;
+  public Integer virtualIdNumber;
 
   public AccountInfo owner;
 
diff --git a/java/com/google/gerrit/server/change/ChangeJson.java b/java/com/google/gerrit/server/change/ChangeJson.java
index 928c8f83ba..7248836377 100644
--- a/java/com/google/gerrit/server/change/ChangeJson.java
+++ b/java/com/google/gerrit/server/change/ChangeJson.java
@@ -773,7 +773,7 @@ public class ChangeJson {
               .collect(toList());
     }
 
-    out._virtualIdNumber = cd.virtualId().get();
+    out.virtualIdNumber = cd.virtualId().get();
 
     return out;
   }
@@ -965,7 +965,7 @@ public class ChangeJson {
     // repository only once
     try (Repository allUsersRepo = repoManager.openRepository(allUsers)) {
       List<Change.Id> changeIds =
-          changeInfos.stream().map(c -> Change.id(c._virtualIdNumber)).collect(Collectors.toList());
+          changeInfos.stream().map(c -> Change.id(c.virtualIdNumber)).collect(Collectors.toList());
       Set<Change.Id> starredChanges =
           starredChangesUtil.areStarred(
               allUsersRepo, changeIds, userProvider.get().asIdentifiedUser().getAccountId());
@@ -973,7 +973,7 @@ public class ChangeJson {
         return;
       }
       changeInfos.stream()
-          .forEach(c -> c.starred = starredChanges.contains(Change.id(c._virtualIdNumber)));
+          .forEach(c -> c.starred = starredChanges.contains(Change.id(c.virtualIdNumber)));
     } catch (IOException e) {
       logger.atWarning().withCause(e).log("Failed to open All-Users repo.");
     }