[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: document protocol version ranges
From: |
gnunet |
Subject: |
[taler-docs] branch master updated: document protocol version ranges |
Date: |
Mon, 30 Mar 2020 11:35:57 +0200 |
This is an automated email from the git hooks/post-receive script.
dold pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new 293b3d5 document protocol version ranges
293b3d5 is described below
commit 293b3d55d8cd6cf946bb4e86bfe8ef743156838b
Author: Florian Dold <address@hidden>
AuthorDate: Mon Mar 30 15:05:45 2020 +0530
document protocol version ranges
---
core/api-common.rst | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 53 insertions(+)
diff --git a/core/api-common.rst b/core/api-common.rst
index 44d4eb0..5fafacb 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -121,6 +121,59 @@ handle the error as if an internal error (500) had been
returned.
type_actual?: string;
}
+-----------------------
+Protocol Version Ranges
+-----------------------
+
+Some of the Taler services (e.g. exchange, merchant, bank integration API)
+expose the range of API versions they support. Clients in turn have an API
+version range they support. These version ranges are written down in the
+`libtool version format
<https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html>`__.
+
+A protocol version is a positive, non-zero integer. A protocol version range
consists of three components:
+
+1. The ``current`` version. This is the latest version of the protocol
supported by the client or service.
+2. The ``revision`` number. This value is not to be interpreted by the
client/server, but serves
+ purely as a comment. Each time a service/client for a protocol is updated
while supporting the same
+ set of protocol versions, the revision should be increased.
+3. The ``age`` number. This non-zero integer identifies with how many
previous protocol versions this
+ implementation is compatible. An ``age`` of 0 implies that the
implementation only supports
+ the ``current`` protocol version. The ``age`` must be less or equal than
the ``current`` protocol version.
+
+To avoid confusion with semantic versions, the protocol version range is
written down in the following format:
+
+.. code:: none
+
+ current[:revision[:age]]
+
+The angle brackets mark optional components. If either ``revision`` or ``age``
are omitted, they default to 0.
+
+Examples:
+
+* "1" and "1" are compatible
+* "1" and "2" are **incompatible**
+* "2:0:1" and "1:0:0" are compatible
+* "2:5:1" and "1:10:0" are compatible
+* "4:0:1" and "2:0:0" are **incompatible**
+* "4:0:1" and "3:0:0" are compatible
+
+.. note::
+
+ `Semantic versions <https://semver.org/>`__ are not a good tool for this
job, as we concisely want to express
+ that the client/server supports the last ``n`` versions of the protocol.
+ Semantic versions don't support this, and semantic version ranges are too
complex for this.
+
+.. warning::
+
+ A client doesn't have one single protocol version range. Instead, it has
+ a protocol version range for each type of service it talks to.
+
+.. warning::
+
+ For privacy reasons, the protocol version range of a client should not be
+ sent to the service. Instead, the client should just use the two version
ranges
+ to decide whether it will talk to the service.
+
.. _encodings-ref:
--
To stop receiving notification emails like this one, please contact
address@hidden.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-docs] branch master updated: document protocol version ranges,
gnunet <=