From ba51d5960ecbc7b820235ad75765c06ccd4da379 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 16 Aug 2018 11:44:48 -0600 Subject: [PATCH 1/6] 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 | 2 +- changelogs/push_gateway.rst | 6 +++ .../push_gateway/newsfragments/.gitignore | 1 + changelogs/push_gateway/pyproject.toml | 30 ++++++++++++ meta/releasing_a_spec.md | 47 +++++++++++++++++++ scripts/gendoc.py | 6 +++ .../templating/matrix_templates/sections.py | 5 ++ scripts/templating/matrix_templates/units.py | 5 +- specification/push_gateway.rst | 19 +++++++- specification/targets.yaml | 2 +- 10 files changed, 117 insertions(+), 6 deletions(-) create mode 100644 changelogs/push_gateway.rst create mode 100644 changelogs/push_gateway/newsfragments/.gitignore create mode 100644 changelogs/push_gateway/pyproject.toml create mode 100644 meta/releasing_a_spec.md diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index 4a6cb8f7..21c1ea29 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/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: diff --git a/changelogs/push_gateway.rst b/changelogs/push_gateway.rst new file mode 100644 index 00000000..33a7683c --- /dev/null +++ b/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. diff --git a/changelogs/push_gateway/newsfragments/.gitignore b/changelogs/push_gateway/newsfragments/.gitignore new file mode 100644 index 00000000..b722e9e1 --- /dev/null +++ b/changelogs/push_gateway/newsfragments/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/changelogs/push_gateway/pyproject.toml b/changelogs/push_gateway/pyproject.toml new file mode 100644 index 00000000..dad1bc04 --- /dev/null +++ b/changelogs/push_gateway/pyproject.toml @@ -0,0 +1,30 @@ +[tool.towncrier] + filename = "../push_gateway.rst" + directory = "newsfragments" + issue_format = "`#{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 diff --git a/meta/releasing_a_spec.md b/meta/releasing_a_spec.md new file mode 100644 index 00000000..cd7033fc --- /dev/null +++ b/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. diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 16c40af5..042e3d9d 100755 --- 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( + "--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)) diff --git a/scripts/templating/matrix_templates/sections.py b/scripts/templating/matrix_templates/sections.py index 1a93c723..65ed7f6d 100644 --- a/scripts/templating/matrix_templates/sections.py +++ b/scripts/templating/matrix_templates/sections.py @@ -31,6 +31,11 @@ class MatrixSections(Sections): def render_client_server_changelog(self): 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") diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 90a87cd4..c400b691 100644 --- 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") + 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 `_", - "unstable", + "`Push Gateway API `_", + push_gw_ver, "Push notifications for Matrix events", ), ]) diff --git a/specification/push_gateway.rst b/specification/push_gateway.rst index e4a9d6ea..e4623887 100644 --- a/specification/push_gateway.rst +++ b/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 `_ as of Git commit `{{git_version}} `_. +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 `_: Includes all changes since the latest versioned release. +- `r0.1.0 `_ + Overview -------- diff --git a/specification/targets.yaml b/specification/targets.yaml index 53957e0a..db869330 100644 --- a/specification/targets.yaml +++ b/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 From 5b73a0174dec6889d00aba7488ffd79df9c319dc Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 14:05:23 -0600 Subject: [PATCH 2/6] Clarify what the release branch is used for, and how it should be named --- meta/releasing_a_spec.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/meta/releasing_a_spec.md b/meta/releasing_a_spec.md index cd7033fc..078d7178 100644 --- a/meta/releasing_a_spec.md +++ b/meta/releasing_a_spec.md @@ -5,10 +5,10 @@ specification, server-server specification, and identity server specification. E 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`. +changes in and to hold potential future hotfixes. This should be the name of the +specification (as it appears in the directory structure of this project) followed +by "release-" and the release version. For example, if the Client-Server Specification +was getting an r0.4.0 release, the branch name would be `client_server/release-r0.4.0`. *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 From e141f61df3a1d8305b3644ba516a1260f41744ec Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 20 Aug 2018 14:05:48 -0600 Subject: [PATCH 3/6] Update release instructions to reference symlinks, what files to update, etc --- meta/releasing_a_spec.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/meta/releasing_a_spec.md b/meta/releasing_a_spec.md index 078d7178..3a9da893 100644 --- a/meta/releasing_a_spec.md +++ b/meta/releasing_a_spec.md @@ -21,12 +21,13 @@ The remainder of the process is as follows: 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. Ensure the `targets.yml` file lists the version correctly. +1. Commit the changes and PR them to master. +1. Tag the release with the format `client_server/r0.4.0`. 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`. + * Don't forget to symlink the new release as `latest`. 1. Perform a release on GitHub to tag the release. 1. Yell from the mountaintop to the world about the new release. From 72c6fa2aaf73af1af9da40c3bdbc31de8369ce7c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 19:33:03 -0600 Subject: [PATCH 4/6] More versioned links --- specification/modules/push.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/modules/push.rst b/specification/modules/push.rst index e9ee8c90..492e8291 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -623,4 +623,4 @@ should send a "sync" command to instruct the client to get new events from the homeserver directly. -.. _`Push Gateway Specification`: ../push_gateway/unstable.html +.. _`Push Gateway Specification`: ../push_gateway/%PUSH_GATEWAY_RELEASE_LABEL%.html From b402608b41ee1e6a73f8e89296ebbfed4bbff3e9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 28 Aug 2018 14:40:14 -0600 Subject: [PATCH 5/6] Don't reference the major version for the push gateway specification If we ever have a v2 endpoint for the push gateway, we'd likely spec it alongside the v1 stuff, updating applicable references elsewhere. --- api/push-gateway/push_notifier.yaml | 2 +- scripts/gendoc.py | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/api/push-gateway/push_notifier.yaml b/api/push-gateway/push_notifier.yaml index 21c1ea29..4a6cb8f7 100644 --- a/api/push-gateway/push_notifier.yaml +++ b/api/push-gateway/push_notifier.yaml @@ -20,7 +20,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/push/%PUSH_GATEWAY_MAJOR_VERSION% +basePath: /_matrix/push/v1 consumes: - application/json produces: diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 042e3d9d..8745d3e2 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -546,7 +546,6 @@ 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, } From 2a20c11467db2e03851b456ec32bdf456273caab Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 17:47:09 -0600 Subject: [PATCH 6/6] Take out the reference to the current version from the changelog --- specification/push_gateway.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/push_gateway.rst b/specification/push_gateway.rst index e4623887..74f9e35e 100644 --- a/specification/push_gateway.rst +++ b/specification/push_gateway.rst @@ -41,7 +41,6 @@ Other versions of this specification The following other versions are also available, in reverse chronological order: - `HEAD `_: Includes all changes since the latest versioned release. -- `r0.1.0 `_ Overview --------