From d9a4ddbf65b2b1dc9aadcc19f3a6ec1283c4779c Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Mon, 18 Dec 2017 13:34:26 +0000
Subject: [PATCH 1/3] Mark `home_server` field deprecated

This is spelt wrong, and is redundant to user_id, so let's stop people using
it.
---
 api/client-server/login.yaml        | 8 ++++++--
 api/client-server/registration.yaml | 8 ++++++--
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml
index ff3eb392..d5bd0f73 100644
--- a/api/client-server/login.yaml
+++ b/api/client-server/login.yaml
@@ -96,7 +96,6 @@ paths:
             application/json: {
                 "user_id": "@cheeky_monkey:matrix.org",
                 "access_token": "abc123",
-                "home_server": "matrix.org",
                 "device_id": "GHTYAJCE"
               }
           schema:
@@ -112,7 +111,12 @@ paths:
                   This access token can then be used to authorize other requests.
               home_server:
                 type: string
-                description: The hostname of the homeserver on which the account has been registered.
+                description: |-
+                  The server_name of the homeserver on which the account has been registered.
+
+                  **Deprecated**. Clients should extract the server_name from
+                  ``user_id`` if they require it. Note also that ``homeserver``
+                  is not spelt this way.
               device_id:
                 type: string
                 description: |-
diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml
index 52693f5b..50839f4e 100644
--- a/api/client-server/registration.yaml
+++ b/api/client-server/registration.yaml
@@ -124,7 +124,6 @@ paths:
             application/json: {
                 "user_id": "@cheeky_monkey:matrix.org",
                 "access_token": "abc123",
-                "home_server": "matrix.org",
                 "device_id": "GHTYAJCE"
               }
           schema:
@@ -144,7 +143,12 @@ paths:
                   This access token can then be used to authorize other requests.
               home_server:
                 type: string
-                description: The hostname of the homeserver on which the account has been registered.
+                description: |-
+                  The server_name of the homeserver on which the account has been registered.
+
+                  **Deprecated**. Clients should extract the server_name from
+                  ``user_id`` if they require it. Note also that ``homeserver``
+                  is not spelt this way.
               device_id:
                 type: string
                 description: |-

From 6a524be585ed01ef688f2441184152be221bb3e1 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Mon, 18 Dec 2017 13:37:30 +0000
Subject: [PATCH 2/3] changelog

---
 changelogs/client_server.rst | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst
index 4a26c302..b0fb8426 100644
--- a/changelogs/client_server.rst
+++ b/changelogs/client_server.rst
@@ -1,7 +1,11 @@
 Unreleased changes
 ==================
 
-No changes as yet.
+- Spec clarifications:
+
+  - Mark ``home_server`` return field for ``/login`` and ``/register``
+    endpoints as deprecated
+    (`#1097 <https://github.com/matrix-org/matrix-doc/pull/1097>`_).
 
 r0.3.0
 ======

From 00b28495a63b18a1a436966ccb673e1e4a0c431b Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Mon, 18 Dec 2017 14:48:56 +0000
Subject: [PATCH 3/3] Explain how to split an mxid

---
 api/client-server/login.yaml        | 7 ++++---
 api/client-server/registration.yaml | 7 ++++---
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml
index d5bd0f73..03a1622c 100644
--- a/api/client-server/login.yaml
+++ b/api/client-server/login.yaml
@@ -112,11 +112,12 @@ paths:
               home_server:
                 type: string
                 description: |-
-                  The server_name of the homeserver on which the account has been registered.
+                  The server_name of the homeserver on which the account has
+                  been registered.
 
                   **Deprecated**. Clients should extract the server_name from
-                  ``user_id`` if they require it. Note also that ``homeserver``
-                  is not spelt this way.
+                  ``user_id`` (by splitting at the first colon) if they require
+                  it. Note also that ``homeserver`` is not spelt this way.
               device_id:
                 type: string
                 description: |-
diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml
index 50839f4e..fd8f6832 100644
--- a/api/client-server/registration.yaml
+++ b/api/client-server/registration.yaml
@@ -144,11 +144,12 @@ paths:
               home_server:
                 type: string
                 description: |-
-                  The server_name of the homeserver on which the account has been registered.
+                  The server_name of the homeserver on which the account has
+                  been registered.
 
                   **Deprecated**. Clients should extract the server_name from
-                  ``user_id`` if they require it. Note also that ``homeserver``
-                  is not spelt this way.
+                  ``user_id`` (by splitting at the first colon) if they require
+                  it. Note also that ``homeserver`` is not spelt this way.
               device_id:
                 type: string
                 description: |-