Prepare the identity service and server-server APIs for r0

* Create the changelog scaffolding * Set up the variables for versioning
6 years ago · d370a2c6fd
parent 5f06694b6f
commit d370a2c6fd
33 changed files with 146 additions and 40 deletions
--- a/api/identity/associations.yaml
+++ b/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:
--- a/api/identity/email_associations.yaml
+++ b/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:
--- a/api/identity/invitation_signing.yaml
+++ b/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:
--- a/api/identity/lookup.yaml
+++ b/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:
--- a/api/identity/phone_associations.yaml
+++ b/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:
--- a/api/identity/ping.yaml
+++ b/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: |-
--- a/api/identity/pubkey.yaml
+++ b/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:
--- a/api/identity/store_invite.yaml
+++ b/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
--- a/api/server-server/backfill.yaml
+++ b/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:
--- a/api/server-server/event_auth.yaml
+++ b/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:
--- a/api/server-server/events.yaml
+++ b/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:
--- a/api/server-server/invites.yaml
+++ b/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:
--- a/api/server-server/joins.yaml
+++ b/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:
--- a/api/server-server/keys_query.yaml
+++ b/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:
--- a/api/server-server/keys_server.yaml
+++ b/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:
--- a/api/server-server/leaving.yaml
+++ b/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:
--- a/api/server-server/openid.yaml
+++ b/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:
--- a/api/server-server/public_rooms.yaml
+++ b/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:
--- a/api/server-server/query.yaml
+++ b/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:
--- a/api/server-server/third_party_invite.yaml
+++ b/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:
--- a/api/server-server/transactions.yaml
+++ b/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:
--- a/api/server-server/version.yaml
+++ b/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:
--- a/changelogs/identity_service.rst
+++ b/changelogs/identity_service.rst
--- a/changelogs/identity_service/newsfragments/.gitignore
+++ b/changelogs/identity_service/newsfragments/.gitignore
@ -0,0 +1 @@
+!.gitignore
--- a/changelogs/identity_service/pyproject.toml
+++ b/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
--- a/changelogs/server_server.rst
+++ b/changelogs/server_server.rst
--- a/changelogs/server_server/newsfragments/.gitignore
+++ b/changelogs/server_server/newsfragments/.gitignore
@ -0,0 +1 @@
+!.gitignore
--- a/changelogs/server_server/pyproject.toml
+++ b/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
--- a/scripts/gendoc.py
+++ b/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
-        # example API URLs. When we have released a new major version,
-        # we'll have to bump it.
+        # we hardcode the major versions. This ends up in the example 
+        # API URLs. When we have released a new major version, we'll
+        # 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))
--- a/scripts/templating/matrix_templates/sections.py
+++ b/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")
--- a/scripts/templating/matrix_templates/units.py
+++ b/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(
--- a/specification/identity_service_api.rst
+++ b/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

 {
--- a/specification/server_server_api.rst
+++ b/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}``.
-Homeservers query for keys by either getting ``/_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/%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 
-query the ``/_matrix/key/v2/server/{keyId}`` API on behalf of another server and
+``/_matrix/key/%KEYS_MAJOR_VERSION%/query/{serverName}/{keyId}`` API. Intermediate notary servers 
+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