Commit Graph

53 Commits

Author SHA1 Message Date
Travis Ralston 9aa47b86c4 Introduce a concept of a room version specification
The "Room Specification" (or "Room Version Specification") is the specification that defines which room versions do what and are intended to be documents which speak the truth about how rooms operate under the hood.

The approach taken here is a bit different than other specifications. For starters, the specification is versioned in this project instead of relying on the matrix.org repository to track compiled HTML. This is done for a couple reasons, the first being we're still developing the v1 specification while concurrently making a v2 spec and the second being trying to reduce the reliance on matrix.org's repository for specifications.

Because the room spec is built into versions, some changes needed to be made. The `targets.yaml` now has a special syntax for indicating what version something is at, and the changelog generator can handle rendering different versions of the same changelog (as parsed from the RST). Some additional work has been put in to the changelog parsing to allow us to reference the v1 room spec as "v1" without having to sacrifice clarity in the changelog headings.

Finally, this moves the identifier grammar as it stands into the v1 room spec. This is in anticipation of the v2 room spec having a different set of grammar. Event schemas haven't been migrated here while the MSC to change them is in-flight.

There are a few open questions at this point:
* Do we move state resolution into here?
* Do we move the auth rules into here?

Note: this does not introduce the concept of versioned schemas (tabs) that I was previously working with. There's currently no use for them, so they are shelved elsewhere.
2018-09-10 16:34:42 -06:00
Travis Ralston 7d34995ece It's actually an "identity server implementing the Identity Service API"
Also add a note about appservices being special.
2018-08-31 15:35:32 -06:00
Travis Ralston 7ac76fa27c Actually we're going with "identity server" afterall 2018-08-31 15:04:00 -06:00
Richard van der Hoff 8773b9319b
Merge pull request from matrix-org/benpa/spec-tables-prettier
Benpa/spec tables prettier
2018-08-31 21:40:55 +01:00
Travis Ralston 84a2b7f3c0
Merge pull request from uhoreg/fix_room_member_state_key
fix handling of multi-line state key descriptions
2018-08-31 14:38:58 -06:00
Ben Parsons e8afab1fe5 many visual improvements 2018-08-31 13:55:27 +01:00
Travis Ralston 98a445890c Render a warning if the spec is unstable
Fixes https://github.com/matrix-org/matrix-doc/issues/1499

This is done by using magic variables in the RST. The magic variables are generated based on the substitutions available, making them available for use at build-time. 

Magic variables were chosen because it allows people to continue working on the spec and release process without having to worry about removing a chunk of text from the top of the file. Originally, this was attempted by using jinja2 if-statements, however the substitutions are replaced *after* the template is executed, so the condition would never match. 

The format of the variable is to make the templating happy. Using colons or percent signs results in the templator thinking something else is going on, and then complaining about format.
2018-08-30 15:05:50 -06:00
Travis Ralston cee0a5ac7b
Merge pull request from turt2live/travis/general/r0-prep
Prepare the identity service and server-server APIs for r0
2018-08-30 14:46:35 -06:00
Hubert Chathi a1b1054aa1 fix handling of multi-line state key descriptions 2018-08-30 15:57:09 -04:00
Travis Ralston 2753d24302 Merge remote-tracking branch 'matrix-org/master' into travis/general/r0-prep 2018-08-30 12:17:09 -06:00
Travis Ralston 827033c128 Merge remote matrix-org/master 2018-08-30 11:29:47 -06:00
Richard van der Hoff f649d04ae1
Merge pull request from matrix-org/rav/encoding
Set the encoding to UTF-8 on all file I/O
2018-08-30 18:11:38 +01:00
Richard van der Hoff 4e90b32348 Set the encoding to UTF-8 on all file I/O
Hopefully this will resolve issues with building the spec on systems where the
default encoding is somthing other than UTF-8.
2018-08-30 17:18:07 +01:00
Ben Parsons 9e1d6d7490 sanitise caption handling 2018-08-30 17:01:27 +01:00
Travis Ralston a5c3924492 Merge remote matrix-org/master 2018-08-29 21:28:24 -06:00
Travis Ralston e7a69a6a6d Merge remote-tracking branch 'matrix-org/master' into travis/general/r0-prep 2018-08-29 19:29:42 -06:00
Travis Ralston 2ab2f91088 Merge remote-tracking branch 'matrix-org/master' into travis/releases/push-gateway/r0.1.0 2018-08-29 17:54:34 -06:00
Ben Parsons 989b50a1a0 remove debug string 2018-08-29 16:40:26 +01:00
Ben Parsons 6e0fe70500 make spec tables prettier 2018-08-29 16:38:59 +01:00
Travis Ralston 4278a9a516 Merge remote-tracking branch 'matrix-org/master' into travis/c2s/fix-events 2018-08-27 19:17:37 -06:00
Travis Ralston fa96d8629b Prepare the appservice spec for an r0 release
This puts the scaffolding in place for an r0 release to happen, such as the changelog and version variables.
2018-08-27 18:04:08 -06:00
Travis Ralston e9e93b0eec Move `invite_room_state` to the correct place in the client-server API
Fixes https://github.com/matrix-org/matrix-doc/issues/1350
2018-08-26 20:51:39 -06:00
Travis Ralston 0f28f83270 Fix client-server event schemas: remove `age`, dedupe fields
This commit adds support for event schema examples to have references to help reduce the chance of fields being forgotten. This also helps reduce duplication of fields, allowing for a more consistent spec that uses the same values everywhere.

This also removes both `unsigned` and `age` from the examples as per:
* https://github.com/matrix-org/matrix-doc/issues/1524
* https://github.com/matrix-org/matrix-doc/issues/630

Finally, this replaces "localhost" in the examples with an example domain. This is really just a nitpick thing on my part where seeing a "real world" domain is preferred. 

Fixes https://github.com/matrix-org/matrix-doc/issues/1524
Fixes https://github.com/matrix-org/matrix-doc/issues/630
Step towards https://github.com/matrix-org/matrix-doc/issues/1530
2018-08-24 18:04:51 -06:00
Travis Ralston d370a2c6fd Prepare the identity service and server-server APIs for r0
* Create the changelog scaffolding
* Set up the variables for versioning
2018-08-24 17:19:25 -06:00
Travis Ralston 750d4f9fda Rename the presence EDU files to be accurate to their types; Misc cleanup of titles 2018-08-17 10:53:47 -06:00
Travis Ralston a53fa9300d Merge remote-tracking branch 'matrix-org/master' into travis/s2s/presence 2018-08-17 09:34:16 -06:00
Travis Ralston ba51d5960e 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.
2018-08-16 11:50:18 -06:00
Kitsune Ral 9be78f3aa7 Better support enums when they come among oneOf types 2018-08-12 16:45:35 +09:00
Kitsune Ral 88d97b06ae Support oneOf 2018-08-12 16:45:33 +09:00
Travis Ralston 05a2427c73 Document how presence EDUs work between servers
It's worth noting that Synapse does not make use of the `poll` or `unpoll` fields, and therefore the wording has been updated to permit servers to reject users. In the case of synapse, it would automatically reject everyone in the list by nature of ignoring it.
2018-08-08 08:24:09 -06:00
Travis Ralston db6d466fa1 Go one level deep when finding definitions
This is useful for when we start defining event schemas. This also has a sanity check for ensuring the directory exists, allowing the IS and push API paths to be uncommented.
2018-08-03 19:49:46 -06:00
Travis Ralston 96f5510266 Ensure the example is always set to something 2018-08-03 12:03:23 -06:00
Travis Ralston ea307b5bdb Support rendering schema definitions in the spec 2018-07-31 13:55:53 -06:00
Travis Ralston acf9632afc Enlist the examples 2018-07-24 10:25:24 -06:00
Travis Ralston 9fa838d3e8 Improve type naming 2018-07-24 10:17:57 -06:00
Travis Ralston 5ade15534d Remove extra branch in example generation 2018-07-24 10:17:39 -06:00
Travis Ralston 042772aaf5 Make nested titles better 2018-07-24 10:13:23 -06:00
Travis Ralston a4e5a461f9 Improve handing of lists appearing in items 2018-07-24 09:14:31 -06:00
Travis Ralston e226b60c7f Merge remote-tracking branch 'matrix-org/master' into travis/s2s/transactions-swagger 2018-07-18 10:59:39 -06:00
Travis Ralston e5da1e1741 Improve upon the transaction schema and examples
Reduces data duplication and makes the objects more reusable for other areas of the spec
2018-07-12 21:34:52 -06:00
Travis Ralston 8a4ba8c5ca Use Popen rather than run() 2018-07-12 10:16:32 -06:00
Travis Ralston af7460088f Use six for url quoting 2018-07-12 10:07:09 -06:00
Travis Ralston 374ec00046 Convert things that mention "Transaction" to swagger
There's two kinds of transactions currently: one with EDUs and one without. The one with EDUs is only used on /send, however the schema is still somewhat worth splitting out for simplicity.

The examples are brought apart to make them slightly more reusable for when they get dumped into the relevant sections of the spec (see TODO in server_server_api.rst)

Further, the Transactions stuff introduces tuples to the spec. The units.py has been updated to support this.
2018-07-11 16:52:27 -06:00
Travis Ralston a8461e647f Improve the error handling for towncrier
The changelog shows up via stdout, everything else via stderr. We dump as much information as we can into the changelog to make debugging errors easier.
2018-07-11 08:35:55 -06:00
Travis Ralston 905ef6dadd Have the towncrier generator complain if the output looks wrong 2018-07-10 16:57:21 -06:00
Travis Ralston ebc7db12fb Remove extraneous list casting 2018-07-10 16:52:17 -06:00
Travis Ralston 7ada960206 Fix the Travis CI build to work on 3.5 2018-07-09 14:55:25 -06:00
Travis Ralston 9277e4c52d Add initial towncrier support 2018-07-06 16:32:27 -06:00
Travis Ralston f54d5a4039 Convert build scripts to python 3 2018-07-06 15:21:07 -06:00
Travis Ralston cbbdcbcf01 Show arrays in the query string as "[type]" rather than "array"
Otherwise the question "array of what?" is raised.
2018-07-03 15:50:01 -06:00