Deprecate query option on List Groups REST endpoint

Support for generic group queries has been added by change I5b9168.
For this we would like to use the --query option so that handling
group queries is consistent with handling account and change queries.
However --query is already in use by the List Groups REST endpoint
and hence the option for generic group queries was named --query2.
This is a temporary naming to maintain backwards compatibility of the
old --query option. Going forward we want to clean this up. This is
why the old --query option is marked as deprecated and instead the
same functionality is offered by a new --group option. When users of
this API had enough time to migrate we may remove the old --query
option and rename the --query2 option to --query. Add this information
to the documentation so that users are warned about this well in
advance.

Change-Id: Ic0b8178593a3c0ac0f26bf96192c6d6b82bd03f8
Signed-off-by: Edwin Kempin <ekempin@google.com>

Documentation/rest-api-groups.txt

@@ -120,8 +120,13 @@ client so they are generally disabled by default. Optional fields are:
 
 ==== Check if a group is owned by the calling user
 By setting the option `owned` and specifying a group to inspect with
-the option `q`, it is possible to find out, if this group is owned by
-the calling user.
+the option `group`/`g`, it is possible to find out if this group is
+owned by the calling user.
+
+[NOTE] Earlier the `group`/`g` option was named `query`/`q`. Using
+`query`/`q` still works, but this option is deprecated and may be
+removed in future. Hence all users should be adapted to use
+`group`/`g` instead.
 
 .Request
 ----
@@ -181,8 +186,8 @@ If this option is set and `n` is not set, then `n` defaults to 10.
 When using this option, the `project` or `p` option can be used to
 name the current project, to allow context-dependent suggestions.
 
-Not compatible with `visible-to-all`, `owned`, `user`, `match`, `q`,
-or `S`.
+Not compatible with `visible-to-all`, `owned`, `user`, `match`,
+`group`, or `S`.
 (Attempts to use one of those options combined with `suggest` will
 error out.)
 
@@ -224,6 +229,11 @@ can be used to skip/limit results.
 
 As result a list of link:#group-info[GroupInfo] entities is returned.
 
+[NOTE] `query2` is a temporary name and in future this option may be
+renamed to `query`. `query2` was chosen to maintain backwards
+compatibility with the deprecated `query` parameter on the
+link:#list-groups[List Groups] endpoint.
+
 .Request
 ----
   GET /groups/?query2=inname:test HTTP/1.0

gerrit-gwtui/src/main/java/com/google/gerrit/client/groups/GroupMap.java

@@ -59,7 +59,7 @@ public class GroupMap extends NativeMap<GroupInfo> {
   }
 
   public static void myOwned(String groupName, AsyncCallback<GroupMap> cb) {
-    myOwnedGroups().addParameter("q", groupName).get(
+    myOwnedGroups().addParameter("g", groupName).get(
         NativeMap.copyKeysIntoChildren(cb));
   }
 

gerrit-server/src/main/java/com/google/gerrit/server/group/ListGroups.java

@@ -106,9 +106,23 @@ public class ListGroups implements RestReadView<TopLevelResource> {
     this.owned = owned;
   }
 
-  @Option(name = "--query", aliases = {"-q"}, usage = "group to inspect")
-  public void addGroup(AccountGroup.UUID id) {
-    groupsToInspect.add(id);
+
+  /**
+   * Add a group to inspect.
+   *
+   * @param uuid UUID of the group
+   * @deprecated use {@link #addGroup(AccountGroup.UUID)}.
+   */
+  @Deprecated
+  @Option(name = "--query", aliases = {"-q"},
+      usage = "group to inspect (deprecated: use --group/-g instead)")
+  void addGroup_Deprecated(AccountGroup.UUID uuid) {
+    addGroup(uuid);
+  }
+
+  @Option(name = "--group", aliases = {"-g"}, usage = "group to inspect")
+  public void addGroup(AccountGroup.UUID uuid) {
+    groupsToInspect.add(uuid);
   }
 
   @Option(name = "--limit", aliases = {"-n"}, metaVar = "CNT",

gerrit-server/src/main/java/com/google/gerrit/server/group/QueryGroups.java

@@ -51,6 +51,8 @@ public class QueryGroups implements RestReadView<TopLevelResource> {
   private EnumSet<ListGroupsOption> options =
       EnumSet.noneOf(ListGroupsOption.class);
 
+  // TODO(ekempin): --query in ListGroups is marked as deprecated, once it is
+  // removed we want to rename --query2 to --query here.
   /** --query (-q) is already used by {@link ListGroups} */
   @Option(name = "--query2", aliases = {"-q2"}, usage = "group query")
   public void setQuery(String query) {