r0.1.0 release of the Push Gateway specification

Because this is the first release, it has several moving parts to it:
* The version variables have been defined.
* The towncrier changelog has been prepared for future modifications.
* The templating has been updated to better support future versions of the specification.
* A release process document has been created.

api/push-gateway/push_notifier.yaml

@@ -20,7 +20,7 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/push/v1
+basePath: /_matrix/push/%PUSH_GATEWAY_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

changelogs/push_gateway.rst

@@ -0,0 +1,6 @@
+r0.1.0
+======
+
+The first release of the Push Gateway specification. This release contains
+a single endpoint, ``/notify``, that pushers may use to send push notifications
+to clients.

changelogs/push_gateway/newsfragments/.gitignore

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

changelogs/push_gateway/pyproject.toml

@@ -0,0 +1,30 @@
+[tool.towncrier]
+    filename = "../push_gateway.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

meta/releasing_a_spec.md

@@ -0,0 +1,47 @@
+# How to release a specification
+
+There are several specifications that belong to matrix, such as the client-server
+specification, server-server specification, and identity server specification. Each
+of these gets released independently of each other with their own version numbers.
+
+Once a specification is ready for release, a branch should be created to track the
+changes in. This should be the name of the specification (as it appears in the directory
+structure of this project) followed by a forward slash and the version being released,
+followed by `_updates`. For example, if the Client-Server Specification was getting 
+an r0.4.0 release, the branch name would be `client_server/r0.4.0_updates`.
+
+*Note*: Historical releases prior to this process may or may not have an appropriate
+release branch. Releases after this document came into place will have an appropriate
+branch.
+
+The remainder of the process is as follows:
+1. Activate your Python 3 virtual environment.
+1. Having checked out the new release branch, navigate your way over to `./changelogs`.
+1. Follow the release instructions provided in the README.md located there.
+1. Update the changelog section of the specification you're releasing to make a reference
+   to the new version.
+1. Update any version/link references across all specifications.
+1. Update the index to list the version correctly.
+1. Add the changes to the matrix-org/matrix.org repository (for historic tracking).
+   * This is done by making a PR to the `unstyled_docs/spec` folder for the version and
+     specification you're releasing.
+1. Commit the changes and PR them to master.
+1. Tag the release with the format `client_server/r0.4.0`.
+1. Perform a release on GitHub to tag the release.
+1. Yell from the mountaintop to the world about the new release.
+
+### Creating a release for a brand-new specification
+
+Some specifications may not have ever had a release, and therefore need a bit more work
+to become ready. 
+
+1. Activate your Python 3 virtual environment.
+1. Having checked out the new release branch, navigate your way over to `./changelogs`.
+1. Follow the "new changelog" instructions provided in the README.md located there.
+1. Open the specification RST file and make some changes:
+   * Using a released specification as a template, update the changelog section.
+   * Use the appropriate changelog variable in the RST.
+1. Create/define the appropriate variables in `gendoc.py`.
+1. Update `targets.yml`.
+1. Update any version/link references across all specifications.
+1. Follow the regular release process.

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(
+        "--push_gateway_release", "-p", action="store", default="unstable",
+        help="The push gateway 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.",
@@ -542,6 +546,8 @@ if __name__ == '__main__':
         "%CLIENT_MAJOR_VERSION%": "r0",
         "%SERVER_RELEASE_LABEL%": args.server_release,
         "%SERVER_MAJOR_VERSION%": extract_major(args.server_release),
+        "%PUSH_GATEWAY_MAJOR_VERSION%": "v1",
+        "%PUSH_GATEWAY_RELEASE_LABEL%": args.push_gateway_release,
     }
 
     exit (main(args.target or ["all"], args.dest, args.nodelete, substitutions))

scripts/templating/matrix_templates/sections.py

@@ -32,6 +32,11 @@ class MatrixSections(Sections):
         changelogs = self.units.get("changelogs")
         return changelogs["client_server"]
     
+    # TODO: We should make this a generic variable instead of having to add functions all the time.
+    def render_push_gateway_changelog(self):
+        changelogs = self.units.get("changelogs")
+        return changelogs["push_gateway"]
+
     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")
+        push_gw_ver = substitutions.get("%PUSH_GATEWAY_RELEASE_LABEL%", "unstable")
 
         # we abuse the typetable to return this info to the templates
         return TypeTable(rows=[
@@ -774,8 +775,8 @@ class MatrixUnits(Units):
                 "unstable",
                 "Mapping of third party IDs to Matrix IDs",
             ), TypeTableRow(
-                "`Push Gateway API <push_gateway/unstable.html>`_",
+                "`Push Gateway API <push_gateway/"+push_gw_ver+".html>`_",
-                "unstable",
+                push_gw_ver,
                 "Push notifications for Matrix events",
             ),
         ])

specification/push_gateway.rst

@@ -1,4 +1,5 @@
 .. Copyright 2016 OpenMarket Ltd
+.. Copyright 2018 New Vector Ltd
 ..
 .. Licensed under the Apache License, Version 2.0 (the "License");
 .. you may not use this file except in compliance with the License.
@@ -21,13 +22,27 @@ the homeserver. This is managed by a distinct entity called the Push Gateway.
 .. contents:: Table of Contents
 .. sectnum::
 
-Specification version
+Changelog
----------------------
+---------
+
+.. topic:: Version: %PUSH_GATEWAY_RELEASE_LABEL%
+{{push_gateway_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/push_gateway.rst
+
+Other versions of this specification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following other versions are also available, in reverse chronological order:
+
+- `HEAD <https://matrix.org/docs/spec/push_gateway/unstable.html>`_: Includes all changes since the latest versioned release.
+- `r0.1.0 <https://matrix.org/docs/spec/push_gateway/r0.1.0.html>`_
+
 Overview
 --------
 

specification/targets.yaml

@@ -25,7 +25,7 @@ targets:
   push_gateway:
     files:
       - push_gateway.rst
-    version_label: unstable
+    version_label: "%PUSH_GATEWAY_RELEASE_LABEL%"
   appendices:
     files:
       - appendices.rst