r0.1.0 release of the Push Gateway specification #1521

turt2live · 2018-08-16T17:54:01Z

Two part PR

The second part is: matrix-org/matrix.org#209 - please review both.

Description

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.

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.

richvdh · 2018-08-20T11:33:43Z

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%


I'm not sure that this is a thing that needs to be populated from a variable. What is the advantage of doing so?

In the event we ever want to link to the current version of the API, or we release a new version, we don't have to update a bunch of links that we may have forgotten about. It doesn't really do much for us right now besides add yet another variable, however it will help us in the future when building links.

But this presupposes that the whole API surface will get a new version code at once. I don't think that is a good assumption.

It feels even worse to have variables for each API. I really don't want a case where we forget to update a link or worse end up releasing a spec with the wrong version codes.

Suggestions welcome.

why assume that /v1/notify won't be valid in the future?

Having talked it over out of band, I have removed it from this. I was confusing the other variable with this one, making communicating the problem harder.

richvdh · 2018-08-20T11:49:25Z

meta/releasing_a_spec.md

+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


we're presupposing that there will be changes to a released spec after it is released? I guess I don't mind if we want to document the process for doing so if we need to, but building it right into the release process seems to send the wrong message.

ah, or maybe it makes more sense to consider this as a release branch for preparing the release - in which case it probably wants a different name, like client_server/release-r0.4.0

This is based off of looking at the history of branches on matrix-doc. Historically this branch has acted similar to the hotfixes branch on synapse, where minor things like typos, css, etc get merged in. In practice, I'm fairly certain we don't have a proper process to get potential hotfixes into the matrix.org served version of the spec. We should probably call it an actual release branch either way though, rather than making it exclusively a hotfix branch.

Worth noting that I'm also the worst and reserved the updates branch naming convention for this PR.

richvdh · 2018-08-20T11:52:12Z

meta/releasing_a_spec.md

+ 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).


should this happen after the rest of the process, so that r0.4.0 is tagged up before we update matrix.org?

This should probably be a thing, yes.

richvdh · 2018-08-20T11:56:23Z

meta/releasing_a_spec.md

+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


it needs latest symlinks too.

richvdh · 2018-08-20T11:56:51Z

meta/releasing_a_spec.md

@@ -0,0 +1,47 @@
+# How to release a specification


+1 for putting this here. I don't know if you know about https:/matrix-org/internal-config/wiki/Specification; either way, I think this makes that redundant and it should be taken away once this is merged.

I was not aware of that, and somehow failed to find it. I was thinking "it's insane that no one has documented this before" though...

richvdh · 2018-08-20T11:58:45Z

meta/releasing_a_spec.md

+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.


how? which file needs changing?

…te, etc

richvdh · 2018-08-28T17:47:22Z

meta/releasing_a_spec.md

-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).


I think there are some bear-traps in here waiting to ensnare the unwary, but the easiest way to find them is probably to try the process out and see what happened for real.

If we ever have a v2 endpoint for the push gateway, we'd likely spec it alongside the v1 stuff, updating applicable references elsewhere.

richvdh · 2018-08-29T23:37:08Z

specification/push_gateway.rst

+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>`_


we haven't historically included the "live" version of the spec in this section: https://matrix.org/docs/spec/client_server/r0.3.0.html#other-versions-of-this-specification does not link to r0.3.0.

(so this probably shouldn't go in until r0.1.0 is tagged and released)

ftr: pulling it out and re-generating the output, then pushing buttons for the release, then putting the changelog item back into master

richvdh

lgtm modulo query about old versions

…/push-gateway/r0.1.0

turt2live requested a review from a team August 16, 2018 17:54

turt2live mentioned this pull request Aug 16, 2018

r0.1.0 release of the Push Gateway specification matrix-org/matrix.org#209

Merged

richvdh requested changes Aug 20, 2018

View reviewed changes

turt2live added 2 commits August 20, 2018 14:05

Clarify what the release branch is used for, and how it should be named

5b73a01

Update release instructions to reference symlinks, what files to upda…

e141f61

…te, etc

turt2live requested a review from richvdh August 20, 2018 20:08

turt2live assigned richvdh Aug 23, 2018

More versioned links

72c6fa2

richvdh reviewed Aug 28, 2018

View reviewed changes

Don't reference the major version for the push gateway specification

b402608

If we ever have a v2 endpoint for the push gateway, we'd likely spec it alongside the v1 stuff, updating applicable references elsewhere.

turt2live requested a review from richvdh August 29, 2018 15:26

turt2live mentioned this pull request Aug 29, 2018

r0 for the Application Services API #1333

Closed

11 tasks

richvdh reviewed Aug 29, 2018

View reviewed changes

richvdh approved these changes Aug 29, 2018

View reviewed changes

turt2live added 2 commits August 29, 2018 17:54

Merge remote-tracking branch 'matrix-org/master' into travis/releases…

2ab2f91

…/push-gateway/r0.1.0

Take out the reference to the current version from the changelog

2a20c11

turt2live merged commit 4c9d672 into master Aug 30, 2018

turt2live deleted the push_gateway/r0.1.0_updates branch August 30, 2018 00:02

RiotTranslateBot pushed a commit to RiotTranslateBot/matrix-doc that referenced this pull request Aug 22, 2023

Document why /state_ids can respond with a 404 (matrix-org#1521)

dd6af5b

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

r0.1.0 release of the Push Gateway specification #1521

r0.1.0 release of the Push Gateway specification #1521

turt2live commented Aug 16, 2018

richvdh Aug 20, 2018

turt2live Aug 20, 2018

richvdh Aug 28, 2018

turt2live Aug 28, 2018

richvdh Aug 28, 2018

turt2live Aug 28, 2018

richvdh Aug 20, 2018

richvdh Aug 20, 2018

turt2live Aug 20, 2018

turt2live Aug 20, 2018

richvdh Aug 20, 2018

turt2live Aug 20, 2018

richvdh Aug 20, 2018

richvdh Aug 20, 2018

turt2live Aug 20, 2018

richvdh Aug 20, 2018

richvdh Aug 28, 2018

richvdh Aug 29, 2018

richvdh Aug 29, 2018

turt2live Aug 29, 2018

richvdh left a comment

r0.1.0 release of the Push Gateway specification #1521

r0.1.0 release of the Push Gateway specification #1521

Conversation

turt2live commented Aug 16, 2018

Two part PR

Description

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richvdh left a comment

Choose a reason for hiding this comment