Document that old change IDs are deprecated and will be removed
Change-Id: I7b23f87ed137ea83f774cf52844c3ae06699cead
diff --git a/Documentation/rest-api-changes.txt b/Documentation/rest-api-changes.txt
index 1cfd3e1..1606b8a 100644
--- a/Documentation/rest-api-changes.txt
+++ b/Documentation/rest-api-changes.txt
@@ -5384,11 +5384,12 @@
[[change-id]]
=== \{change-id\}
-Identifier that uniquely identifies one change.
+Identifier that uniquely identifies one change. It contains the URL-encoded
+project name as well as the change number: "'$$<project>~<numericId>$$'"
-This can be:
+Depending on the server's configuration, Gerrit can still support the following
+deprecated identifiers. These will be removed in a future release:
-* an ID of the change in the format "'$$<project>~<numericId>$$'"
* an ID of the change in the format "'$$<project>~<branch>~<Change-Id>$$'",
where for the branch the `refs/heads/` prefix can be omitted
("$$myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940$$")
@@ -5396,6 +5397,10 @@
("I8473b95934b5732ac55d26311a706c9c2bde9940")
* a numeric change ID ("4247")
+If you need more time to migrate off of old change IDs, please see
+link:config-gerrit.html#change.api.allowedIdentifier[change.api.allowedIdentifier]
+for more information on how to enable the use of deprecated identifiers.
+
[[comment-id]]
=== \{comment-id\}
UUID of a published comment.
