Convert issues to RFC

issues/README.rst

@@ -3,7 +3,7 @@ Note
 
 SECoP Issues have been replaced by the RFC process, which is described in
 `RFC 1
-<https://github.com/SampleEnvironment/SECoP/blob/master/rfcs/RFC-001-RFC-process.rst>`_.
+<https://github.com/SampleEnvironment/SECoP/blob/master/rfcs/RFC-000-RFC-process.rst>`_.
 
 If there is renewed interest in one of the remaining open issues, please
 migrate to an RFC before restarting discussion.

protocol/specification/changes.rst

@@ -51,11 +51,11 @@ loss of functionality.
 - The :ref:`matrix <matrix>` data type has been specified for datainfo.
 
 - The `AcquisitionController`, `AcquisitionChannel` and `Acquisition` interface
-  classes have been specified (:ref:`rfc-006`).
+  classes have been specified (:ref:`rfc-106`).
 
-- The UDP discovery protocol has been specified (:ref:`rfc-005`).
+- The UDP discovery protocol has been specified (:ref:`rfc-105`).
 
-- Optional SECoP transport over WebSockets has been specified (:ref:`rfc-007`).
+- Optional SECoP transport over WebSockets has been specified (:ref:`rfc-107`).
 
 
 Version 1.1

protocol/specification/classes.rst

@@ -83,7 +83,7 @@ The following terms are relevant here:
   quantity.  An acquisition can acquire data for one or more channels at the
   same time.
 
-See also :secop-rfc:`006-acquisition`.
+See also :ref:`rfc-106`.
 
 .. baseclass:: AcquisitionController
 

protocol/specification/discovery.rst

@@ -80,4 +80,4 @@ Implementation hints
   necessary.
 
 
-See also :ref:`rfc-005`.
+See also :ref:`rfc-105`.

protocol/specification/transport.rst

@@ -104,7 +104,7 @@ exchanging raw SECoP messages is not an option.  The best alternative is
 WebSockets (:rfc:`6455`), which are a relatively overhead-free way of
 exchanging messages between two endpoints in an arbitrary pattern.
 
-See also :ref:`rfc-007`.
+See also :ref:`rfc-107`.
 
 Implementation in a SEC node
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

rfcs/RFC-001-RFC-process.rst → rfcs/RFC-000-rfc-process.rst

@@ -62,7 +62,7 @@ How to contribute
 Here we lay out the steps to follow to change the specification.
 
 - If you do not have a concrete idea, come talk to us to flesh it out.
-- Copy the RFC-000-template.rst file and fill in the details. You can add
+- Copy the RFC-template.rst file and fill in the details. You can add
   sections freely, but try to fill out all the provided ones.
 - Take the next free number and add it to the template file.  Renumbering might
   happen when the PR is merged.

rfcs/RFC-001-issues.rst

@@ -0,0 +1,61 @@
+- Feature: About SECoP Issues
+- Status: Obsolete
+- Submit Date: 2017-05-30
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+This issue describes the "SECoP Issues", the original format of documents that
+preceded the RFC system.  As such, it is no longer relevant, please see
+:ref:`rfc-000` for the current rules for discussing SECoP extensions.
+
+
+Issue text
+==========
+
+The idea behind SECoP Issues is to document properly what was proposed,
+what was discussed, what was decided and why it was decided.
+
+An issue might take different states:
+
+(u) unspecified
+---------------
+
+A vague idea, but no proposal written down yet.
+
+(p) proposed
+------------
+
+A proposal should contain the motivation. As long as nobody else
+joins into a discussion, the state remains *proposed*.
+
+(d) under discussion
+--------------------
+
+This state is kept until a decision is taken.
+
+(f) finalizing
+--------------
+
+This state is kept until the specification change is agreed.
+
+( ) closed
+----------
+
+After a decision the state is *closed*. The issue is not deleted,
+even if the decision was to not follow further the proposal.
+This is helpful if somebody later raises a similar issue.
+However, it should be possible to reopen an issue, if new
+arguments arise.
+
+Remark:
+-------
+
+At the meeting in Lund (13th June 2018), it was agreed not to follow the proposal
+of creating a new state "extensible" for an issue containing an extensible
+list. Instead, an new issue should be created, containing the added elements.
+A full actual list should be added each time.

rfcs/RFC-002-describe-specifier.rst

@@ -0,0 +1,43 @@
+- Feature: Equipment ID in Describing Message
+- Status: Rejected
+- Submit Date: 2017-05-30
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+Could the equipment ID go into the "specifier" field of the "describing"
+message?
+
+
+Issue text
+==========
+
+The equipment ID is a SEC node property, and it is therefore redundant
+to put it as the second item of the describe message.
+
+However as the describe/describing message might be extended later, for
+example to get the description of single modules only, we should specify
+a fixed word for the second item of the describe message, for example the
+keyword "ALL" or "All".
+
+At the meeting in Berlin (2017-05-30) this was discussed, but it was not
+yet decided the the keyword should be exactly. Until a final decision,
+SECoP clients should ignore the second item.
+
+Opinions
+--------
+
+We should use key keyword ALL (Markus Zolliker).
+
+Decision
+--------
+
+The decision was taken to use a bare period as placeholder:
+
+.. code::
+
+    describing . {"modules": ...

rfcs/RFC-003-timestamps.rst

@@ -0,0 +1,68 @@
+- Feature: Timestamp Format
+- Status: Final
+- Submit Date: 2017-05-30
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+Which format should timestamps in value qualifiers take?
+
+
+Issue text
+==========
+
+Proposals for the timestamp format are:
+
+ISO time format
+---------------
+
+A date+time string in ISO format like "2017-06-21T13:30:01.123456+02:00"
+
+The fractional seconds are optional, but the timezone has to be given. Z is allowed instead of +00:00.
+
+Advantages:
+
+* human readable
+
+Disadvantages:
+
+* needs more conversion efforts, as the time is internally already stored as
+  numbers on mosts systems (supporting math operations)
+* although the ISO standard is clearly defined, there is a risk that time zones
+  and daylight saving time is not handled properly
+
+Fractional Unix Time
+--------------------
+
+Seconds since 1970-01-01T00:00:00+00:00, represented as a number. When converted
+to a IEEE double, a resolution of 1 usec can be kept for dates up to 2112.
+
+Advantages:
+
+* if a double is used as an internal representation, no conversion is
+  needed. using a double as an internal time representation has the advantage,
+  that math operations can be done for free.
+* relative times for systems with no synchronized clock can be represented
+  easily
+
+Disadvantages:
+
+* not human readable (or at least not easily: time differences in seconds are
+  still visible)
+
+Discussion
+----------
+
+1) Human readibility was judged less important than easy implementaion by the majority.
+
+2) Implementing relative times is also easier.
+
+Decision
+--------
+
+At the meeting in Berlin (2017-05-30) the attendes decided for "Fractional Unix Time".
+The resolution of the timestamp depends on the hardware, but must be at least one second.

rfcs/RFC-004-timeout-property.rst

@@ -0,0 +1,38 @@
+- Feature: The Timeout SEC Node Property
+- Status: Final
+- Submit Date: 2017-05-30
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+Specifies how to select a suitable response timeout for a SEC node.
+
+
+Issue text
+==========
+
+For a SECoP client, in order to detect that a connection to a SECoP server is dead,
+'ping' messages can be sent. When no 'pong' message is received within a specified
+time, then the client can consider the connection as dead.
+
+If the server does not specify a the SEC node property 'timeout', the timeout
+is assumed to be 3s.
+
+Opinions
+--------
+
+On the meeting in Garching (2017-09-14) it was proposed to fix this a standard.
+
+
+Decision
+--------
+
+It is assumed that when a SEC node is not replying within *timeout*
+seconds, the client may assume that the SEC node is dead or stuck.
+
+If *timeout* is not specfied as a SEC node property. it is assumed to
+be 10 seconds.

rfcs/RFC-005-qualifiers.rst

@@ -0,0 +1,51 @@
+- Feature: Definition of the term 'Qualifier'
+- Status: Final
+- Submit Date: 2017-05-30
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+Specifies qualifiers as the "properties" of live data.
+
+
+Issue text
+==========
+
+The definition as in SECoP V2016-11-30 draft is not very consistent.
+
+As decriptive data we have:
+
+- SEC node properties
+- module properties
+- parameters properties
+- command properties
+
+Live data may be:
+- value
+- timestamp 't'
+- sigma 'e'
+
+It is confusing to use the same term 'property' for live data and for
+descriptive data.
+
+The section with the definition of properties has to be rewritten.
+
+Opinions
+--------
+
+Enrico proposed to name live data like timestamps and sigma *qualifiers*.
+
+Markus supports this. He would be happy also with a term other than
+*qualifiers*, but definitely does not like the terms *live properties* and
+*descriptive properties*, as two different things share the same name.
+
+
+Decision
+--------
+
+Additional information transported with an update message like timestamps and
+sigma are called *qualifiers*.

rfcs/RFC-006-keepalive.rst

@@ -0,0 +1,40 @@
+- Feature: Keep Alive
+- Status: Rejected
+- Submit Date: 2017-05-30
+- Authors: SECoP committee
+- Type: Issue
+- PR:
+- Version: 1.0
+
+Summary
+=======
+
+Does the SEC node need a mechanism to detect "dead" client connections?
+
+
+Issue text
+==========
+
+For a SECoP server, in order to detect that a client connection is dead,
+it might close a connection with no messages within a defined period of time.
+
+The discussed mechanism is:
+
+The SECoP client has to set the connection parameter 'keepalive' to a value
+representing the number of seconds it will send 'ping' (or other) messages.
+The SECoP server can close connections with no messages for a time period
+well above this value (more than 10% higher).
+
+Opinions
+--------
+
+Markus proposes to mention the 10 % in the specification.
+It should also be mentioned, that for keeping the connection alive
+any message might be sent instead of the ping message.
+
+Decision
+--------
+
+We close this issue, not defining such a mechanism.
+If in an implementation pending dead connections arise to be problem
+to the SEC node server, we might reopen the issue.