From c2fc1a2fb19c6a46cc2bde736222f855f0f8ba3d Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Mon, 28 Sep 2015 13:41:31 +0100 Subject: [PATCH 1/4] Add basic module template. This has the core sections for events/server/client/security. --- specification/modules/_template.rst | 47 +++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 specification/modules/_template.rst diff --git a/specification/modules/_template.rst b/specification/modules/_template.rst new file mode 100644 index 00000000..6ea7aaa3 --- /dev/null +++ b/specification/modules/_template.rst @@ -0,0 +1,47 @@ +Module Heading +============== + +.. _module:short-name: + +A short summary of the module. What features does this module provide? An anchor +should be specified at the top of the module using the format ``module:name``. + +Complicated modules may wish to have architecture diagrams or event flows +(e.g. VoIP call flows) here. Custom subsections can be included but they should +be used *sparingly* to reduce the risk of putting client or server behaviour +information in these custom sections. + +Events +------ +List the new event types introduced by this module, if any. If there are no +new events, this section can be omitted. Event types should be done as +subsections. The section is intended to document the "common shared event +structure" between client and server. Deviations from this shared structure +should be documented in the relevant behaviour section. + +example.event.type +~~~~~~~~~~~~~~~~~~ +There should be JSON Schema docs for this event. You can insert a template like +so: + +{{example_event_type_event}} + +Client behaviour +---------------- +List any new HTTP endpoints. List the steps the client needs to take to +correctly process this module. Listing what data structures the client should be +storing to aid implementation is recommended. + +Server behaviour +---------------- +Does the server need to handle any of the new events in a special way (e.g. +typing timeouts, presence). Advice on how to persist events and/or requests are +recommended to aid implementation. + +Security considerations +----------------------- +This includes privacy leaks: for example leaking presence info. How do +misbehaving clients or servers impact this module? This section should always be +included, if only to say "we've thought about it but there isn't anything to do +here". + From 643468e9141902499550ace65da1bf8eb7e53bc5 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Mon, 28 Sep 2015 14:01:54 +0100 Subject: [PATCH 2/4] Mention swagger. Clarify how event type template vars are formed. --- specification/modules/_template.rst | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/specification/modules/_template.rst b/specification/modules/_template.rst index 6ea7aaa3..967892a5 100644 --- a/specification/modules/_template.rst +++ b/specification/modules/_template.rst @@ -19,18 +19,24 @@ subsections. The section is intended to document the "common shared event structure" between client and server. Deviations from this shared structure should be documented in the relevant behaviour section. -example.event.type -~~~~~~~~~~~~~~~~~~ -There should be JSON Schema docs for this event. You can insert a template like -so: +m.example.event.type +~~~~~~~~~~~~~~~~~~~~ +There should be JSON Schema docs for this event. Once there is JSON schema, +there will be a template variable with dots in the event type replaced with +underscores. You can insert a template like so: -{{example_event_type_event}} +{{m_example_event_type_event}} Client behaviour ---------------- -List any new HTTP endpoints. List the steps the client needs to take to +List any new HTTP endpoints. These endpoints should be docced using Swagger. You +can insert a template for swagger docs like so: + +{{name-of-yaml-file-without-file-ext_http_api}} + +List the steps the client needs to take to correctly process this module. Listing what data structures the client should be -storing to aid implementation is recommended. +storing to aid implementation is recommended. Server behaviour ---------------- From 70518ae655eb9fae6ac49a3a1ddea700c7defc44 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Mon, 28 Sep 2015 14:03:54 +0100 Subject: [PATCH 3/4] Clarify template suffixes --- specification/modules/_template.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/specification/modules/_template.rst b/specification/modules/_template.rst index 967892a5..bb662c05 100644 --- a/specification/modules/_template.rst +++ b/specification/modules/_template.rst @@ -23,14 +23,16 @@ m.example.event.type ~~~~~~~~~~~~~~~~~~~~ There should be JSON Schema docs for this event. Once there is JSON schema, there will be a template variable with dots in the event type replaced with -underscores. You can insert a template like so: +underscores and the suffix ``_event``. You can insert a template like so: {{m_example_event_type_event}} Client behaviour ---------------- -List any new HTTP endpoints. These endpoints should be docced using Swagger. You -can insert a template for swagger docs like so: +List any new HTTP endpoints. These endpoints should be docced using Swagger. +Once there is Swagger, there will be a template variable based on the name of +the YAML file with the suffix ``_http_api``. You can insert a template for +swagger docs like so: {{name-of-yaml-file-without-file-ext_http_api}} From 5abea1f2bc2d36789164a4682cb8a668fb684845 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Mon, 28 Sep 2015 14:07:34 +0100 Subject: [PATCH 4/4] Minor tweaks --- specification/modules/_template.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/specification/modules/_template.rst b/specification/modules/_template.rst index bb662c05..9eee9843 100644 --- a/specification/modules/_template.rst +++ b/specification/modules/_template.rst @@ -15,12 +15,12 @@ Events ------ List the new event types introduced by this module, if any. If there are no new events, this section can be omitted. Event types should be done as -subsections. The section is intended to document the "common shared event +subsections. This section is intended to document the "common shared event structure" between client and server. Deviations from this shared structure should be documented in the relevant behaviour section. -m.example.event.type -~~~~~~~~~~~~~~~~~~~~ +``m.example.event.type`` +~~~~~~~~~~~~~~~~~~~~~~~~ There should be JSON Schema docs for this event. Once there is JSON schema, there will be a template variable with dots in the event type replaced with underscores and the suffix ``_event``. You can insert a template like so: @@ -29,7 +29,7 @@ underscores and the suffix ``_event``. You can insert a template like so: Client behaviour ---------------- -List any new HTTP endpoints. These endpoints should be docced using Swagger. +List any new HTTP endpoints. These endpoints should be documented using Swagger. Once there is Swagger, there will be a template variable based on the name of the YAML file with the suffix ``_http_api``. You can insert a template for swagger docs like so: @@ -37,14 +37,15 @@ swagger docs like so: {{name-of-yaml-file-without-file-ext_http_api}} List the steps the client needs to take to -correctly process this module. Listing what data structures the client should be -storing to aid implementation is recommended. +correctly process this module. List what data structures the client should be +storing in order to aid implementation. Server behaviour ---------------- Does the server need to handle any of the new events in a special way (e.g. typing timeouts, presence). Advice on how to persist events and/or requests are -recommended to aid implementation. +recommended to aid implementation. Federation-specific logic should be included +here. Security considerations -----------------------