Prepare the identity service and server-server APIs for r0

* Create the changelog scaffolding
* Set up the variables for versioning

api/identity/associations.yaml

@@ -19,7 +19,7 @@ host: localhost:8090
 schemes:
   - https
   - http
-basePath: /_matrix/identity/api/v1
+basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION%
 produces:
   - application/json
 paths:

api/identity/email_associations.yaml

@@ -19,7 +19,7 @@ host: localhost:8090
 schemes:
   - https
   - http
-basePath: /_matrix/identity/api/v1
+basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION%
 produces:
   - application/json
 paths:

api/identity/invitation_signing.yaml

@@ -19,7 +19,7 @@ host: localhost:8090
 schemes:
   - https
   - http
-basePath: /_matrix/identity/api/v1
+basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION%
 produces:
   - application/json
 paths:

api/identity/lookup.yaml

@@ -21,7 +21,7 @@ host: localhost:8090
 schemes:
   - https
   - http
-basePath: /_matrix/identity/api/v1
+basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION%
 produces:
   - application/json
 paths:

api/identity/phone_associations.yaml

@@ -19,7 +19,7 @@ host: localhost:8090
 schemes:
   - https
   - http
-basePath: /_matrix/identity/api/v1
+basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION%
 produces:
   - application/json
 paths:

api/identity/ping.yaml

@@ -23,7 +23,7 @@ basePath: /_matrix/identity
 produces:
   - application/json
 paths:
-  "/api/v1":
+  "/api/%IDENTITY_MAJOR_VERSION%":
     get:
       summary: Checks that an Identity server is available at this API endpopint.
       description: |-

api/identity/pubkey.yaml

@@ -19,7 +19,7 @@ host: localhost:8090
 schemes:
   - https
   - http
-basePath: /_matrix/identity/api/v1
+basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION%
 produces:
   - application/json
 paths:

api/identity/store_invite.yaml

@@ -19,7 +19,7 @@ host: localhost:8090
 schemes:
   - https
   - http
-basePath: /_matrix/identity/api/v1
+basePath: /_matrix/identity/api/%IDENTITY_MAJOR_VERSION%
 produces:
   - application/json
 paths:
@@ -46,7 +46,7 @@ paths:
         ``address`` parameter, notifying them of the invitation.
 
         Also, the generated ephemeral public key will be listed as valid on
-        requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
+        requests to ``/_matrix/identity/api/%IDENTITY_MAJOR_VERSION%/pubkey/ephemeral/isvalid``.
       operationId: storeInvite
       parameters:
         - in: body

api/server-server/backfill.yaml

@@ -19,7 +19,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/federation/v1
+basePath: /_matrix/federation/%SERVER_MAJOR_VERSION%
 consumes: 
   - application/json
 produces:

api/server-server/event_auth.yaml

@@ -19,7 +19,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/federation/v1
+basePath: /_matrix/federation/%SERVER_MAJOR_VERSION%
 consumes: 
   - application/json
 produces:

api/server-server/events.yaml

@@ -19,7 +19,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/federation/v1
+basePath: /_matrix/federation/%SERVER_MAJOR_VERSION%
 produces:
   - application/json
 securityDefinitions:

api/server-server/invites.yaml

@@ -19,7 +19,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/federation/v1
+basePath: /_matrix/federation/%SERVER_MAJOR_VERSION%
 consumes: 
   - application/json
 produces:

api/server-server/joins.yaml

@@ -19,7 +19,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/federation/v1
+basePath: /_matrix/federation/%SERVER_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/server-server/keys_query.yaml

@@ -19,7 +19,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/key/v2
+basePath: /_matrix/key/%KEYS_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/server-server/keys_server.yaml

@@ -19,7 +19,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/key/v2
+basePath: /_matrix/key/%KEYS_MAJOR_VERSION%
 produces:
   - application/json
 paths:

api/server-server/leaving.yaml

@@ -19,7 +19,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/federation/v1
+basePath: /_matrix/federation/%SERVER_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/server-server/openid.yaml

@@ -20,7 +20,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/federation/v1
+basePath: /_matrix/federation/%SERVER_MAJOR_VERSION%
 produces:
   - application/json
 paths:

api/server-server/public_rooms.yaml

@@ -19,7 +19,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/federation/v1
+basePath: /_matrix/federation/%SERVER_MAJOR_VERSION%
 produces:
   - application/json
 securityDefinitions:

api/server-server/query.yaml

@@ -20,7 +20,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/federation/v1
+basePath: /_matrix/federation/%SERVER_MAJOR_VERSION%
 produces:
   - application/json
 securityDefinitions:

api/server-server/third_party_invite.yaml

@@ -19,7 +19,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/federation/v1
+basePath: /_matrix/federation/%SERVER_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/server-server/transactions.yaml

@@ -19,7 +19,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/federation/v1
+basePath: /_matrix/federation/%SERVER_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/server-server/version.yaml

@@ -19,7 +19,7 @@ info:
 host: localhost:8448
 schemes:
   - https
-basePath: /_matrix/federation/v1
+basePath: /_matrix/federation/%SERVER_MAJOR_VERSION%
 produces:
   - application/json
 paths:

changelogs/identity_service/newsfragments/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelogs/identity_service/pyproject.toml

@@ -0,0 +1,30 @@
+[tool.towncrier]
+    filename = "../identity_service.rst"
+    directory = "newsfragments"
+    issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
+    title_format = "{version}"
+    
+    [[tool.towncrier.type]]
+        directory = "breaking"
+        name = "Breaking Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "deprecation"
+        name = "Deprecations"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "new"
+        name = "New Endpoints"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "feature"
+        name = "Backwards Compatible Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "clarification"
+        name = "Spec Clarifications"
+        showcontent = true

changelogs/server_server/newsfragments/.gitignore

@@ -0,0 +1 @@
+!.gitignore

changelogs/server_server/pyproject.toml

@@ -0,0 +1,30 @@
+[tool.towncrier]
+    filename = "../server_server.rst"
+    directory = "newsfragments"
+    issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
+    title_format = "{version}"
+    
+    [[tool.towncrier.type]]
+        directory = "breaking"
+        name = "Breaking Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "deprecation"
+        name = "Deprecations"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "new"
+        name = "New Endpoints"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "feature"
+        name = "Backwards Compatible Changes"
+        showcontent = true
+    
+    [[tool.towncrier.type]]
+        directory = "clarification"
+        name = "Spec Clarifications"
+        showcontent = true

scripts/gendoc.py

@@ -518,6 +518,10 @@ if __name__ == '__main__':
         "--server_release", "-s", action="store", default="unstable",
         help="The server-server release tag to generate, e.g. r1.2"
     )
+    parser.add_argument(
+        "--identity_release", "-i", action="store", default="unstable",
+        help="The identity service release tag to generate, e.g. r1.2"
+    )
     parser.add_argument(
         "--list_targets", action="store_true",
         help="Do not update the specification. Instead print a list of targets.",
@@ -536,12 +540,15 @@ if __name__ == '__main__':
 
     substitutions = {
         "%CLIENT_RELEASE_LABEL%": args.client_release,
-        # we hardcode a major version of r0. This ends up in the
+        # we hardcode the major versions. This ends up in the example 
-        # example API URLs. When we have released a new major version,
+        # API URLs. When we have released a new major version, we'll
-        # we'll have to bump it.
+        # have to bump them.
         "%CLIENT_MAJOR_VERSION%": "r0",
+        "%SERVER_MAJOR_VERSION%": "v1",
+        "%IDENTITY_MAJOR_VERSION%": "v1",
+        "%KEYS_MAJOR_VERSION%": "v2",
         "%SERVER_RELEASE_LABEL%": args.server_release,
-        "%SERVER_MAJOR_VERSION%": extract_major(args.server_release),
+        "%IDENTITY_RELEASE_LABEL%": args.identity_release,
     }
 
     exit (main(args.target or ["all"], args.dest, args.nodelete, substitutions))

scripts/templating/matrix_templates/sections.py

@@ -32,6 +32,14 @@ class MatrixSections(Sections):
         changelogs = self.units.get("changelogs")
         return changelogs["client_server"]
 
+    def render_identity_service_changelog(self):
+        changelogs = self.units.get("changelogs")
+        return changelogs["identity_service"]
+
+    def render_server_server_changelog(self):
+        changelogs = self.units.get("changelogs")
+        return changelogs["server_server"]
+
     def _render_events(self, filterFn, sortFn):
         template = self.env.get_template("events.tmpl")
         examples = self.units.get("event_examples")

scripts/templating/matrix_templates/units.py

@@ -754,6 +754,7 @@ class MatrixUnits(Units):
     def load_apis(self, substitutions):
         cs_ver = substitutions.get("%CLIENT_RELEASE_LABEL%", "unstable")
         fed_ver = substitutions.get("%SERVER_RELEASE_LABEL%", "unstable")
+        is_ver = substitutions.get("%IDENTITY_RELEASE_LABEL%", "unstable")
 
         # we abuse the typetable to return this info to the templates
         return TypeTable(rows=[
@@ -770,7 +771,7 @@ class MatrixUnits(Units):
                 "unstable",
                 "Privileged server plugins",
             ), TypeTableRow(
-                "`Identity Service API <identity_service/unstable.html>`_",
+                "`Identity Service API <identity_service/"+is_ver+".html>`_",
                 "unstable",
                 "Mapping of third party IDs to Matrix IDs",
             ), TypeTableRow(

specification/identity_service_api.rst

@@ -28,13 +28,27 @@ practice has only been applied specifically to email addresses.
 .. contents:: Table of Contents
 .. sectnum::
 
-Specification version
+Changelog
----------------------
+---------
+
+.. topic:: Version: %IDENTITY_RELEASE_LABEL%
+{{identity_service_changelog}}
 
 This version of the specification is generated from
 `matrix-doc <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
 `{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
 
+For the full historical changelog, see
+https://github.com/matrix-org/matrix-doc/blob/master/changelogs/identity_service.rst
+
+
+Other versions of this specification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following other versions are also available, in reverse chronological order:
+
+- `HEAD <https://matrix.org/docs/spec/identity_service/unstable.html>`_: Includes all changes since the latest versioned release.
+
 General principles
 ------------------
 
@@ -138,7 +152,7 @@ associated with a Matrix user ID.
 
 At a later point, if the owner of that particular 3pid binds it with a Matrix user ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver which looks roughly as below::
 
- POST https://bar.com:8448/_matrix/federation/v1/3pid/onbind
+ POST https://bar.com:8448/_matrix/federation/%SERVER_MAJOR_VERSION%/3pid/onbind
  Content-Type: application/json
 
  {

specification/server_server_api.rst

@@ -64,13 +64,27 @@ request.
 .. contents:: Table of Contents
 .. sectnum::
 
-Specification version
+Changelog
----------------------
+---------
+
+.. topic:: Version: %SERVER_RELEASE_LABEL%
+{{server_server_changelog}}
 
 This version of the specification is generated from
 `matrix-doc <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
 `{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
 
+For the full historical changelog, see
+https://github.com/matrix-org/matrix-doc/blob/master/changelogs/server_server.rst
+
+
+Other versions of this specification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following other versions are also available, in reverse chronological order:
+
+- `HEAD <https://matrix.org/docs/spec/server_server/unstable.html>`_: Includes all changes since the latest versioned release.
+
 Server Discovery
 ----------------
 
@@ -118,11 +132,11 @@ Retrieving Server Keys
   specification due to lack of significance. It may be reviewed `here
   <https://github.com/matrix-org/matrix-doc/blob/51faf8ed2e4a63d4cfd6d23183698ed169956cc0/specification/server_server_api.rst#232version-1>`_.
 
-Each homeserver publishes its public keys under ``/_matrix/key/v2/server/{keyId}``.
+Each homeserver publishes its public keys under ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{keyId}``.
-Homeservers query for keys by either getting ``/_matrix/key/v2/server/{keyId}``
+Homeservers query for keys by either getting ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{keyId}``
 directly or by querying an intermediate notary server using a
-``/_matrix/key/v2/query/{serverName}/{keyId}`` API. Intermediate notary servers 
+``/_matrix/key/%KEYS_MAJOR_VERSION%/query/{serverName}/{keyId}`` API. Intermediate notary servers 
-query the ``/_matrix/key/v2/server/{keyId}`` API on behalf of another server and
+query the ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{keyId}`` API on behalf of another server and
 sign the response with their own key. A server may query multiple notary servers to
 ensure that they all report the same public keys.
 
@@ -138,7 +152,7 @@ Publishing Keys
 +++++++++++++++
 
 Homeservers publish the allowed TLS fingerprints and signing keys in a JSON
-object at ``/_matrix/key/v2/server/{key_id}``. The response contains a list of
+object at ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{key_id}``. The response contains a list of
 ``verify_keys`` that are valid for signing federation requests made by the
 homeserver and for signing events. It contains a list of ``old_verify_keys`` which
 are only valid for signing events. Finally the response contains a list of TLS
@@ -152,7 +166,7 @@ Querying Keys Through Another Server
 
 Servers may query another server's keys through a notary server. The notary
 server may be another homeserver. The notary server will retrieve keys from
-the queried servers through use of the ``/_matrix/key/v2/server/{keyId}``
+the queried servers through use of the ``/_matrix/key/%KEYS_MAJOR_VERSION%/server/{keyId}``
 API. The notary server will additionally sign the response from the queried
 server before returning the results.
 
@@ -1073,7 +1087,7 @@ that are too long.
   known hash functions like SHA-256 when none of the keys have been redacted]]
 
 .. |/query/directory| replace:: ``/query/directory``
-.. _/query/directory: #get-matrix-federation-v1-query-directory
+.. _/query/directory: #get-matrix-federation-%SERVER_MAJOR_VERSION%-query-directory
 
 .. _`Invitation storage`: ../identity_service/unstable.html#invitation-storage
 .. _`Identity Service API`: ../identity_service/unstable.html