[tor-commits] [onionoo/master] Add next_major_version_scheduled field.
karsten at torproject.org
karsten at torproject.org
Tue Sep 16 14:16:23 UTC 2014
commit f04a923ecccb1dbcdcfbe3cb7da4e24a331a1422
Author: Karsten Loesing <karsten.loesing at gmx.net>
Date: Tue Sep 16 15:39:51 2014 +0200
Add next_major_version_scheduled field.
Discussed with iwakeh in #12905.
---
ChangeLog | 8 +-
.../torproject/onionoo/server/ResponseBuilder.java | 16 +++-
web/protocol.html | 90 +++++++++++++++++++-
3 files changed, 105 insertions(+), 9 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 2a1fe71..533541b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,12 @@
Changes in version ?.?.? - 2014-??-??
+ o Minor protocol changes:
+ - Add optional field "next_major_version_scheduled", changing protocol
+ version to 1.1. Implements #12905.
+
Changes in version 1.0.0 - 2014-09-16
- - First assigned version number.
+
+ o Major protocol changes.
+ - First assigned version number.
diff --git a/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java b/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java
index c951fd3..d304c4d 100644
--- a/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java
+++ b/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java
@@ -69,12 +69,20 @@ public class ResponseBuilder {
return this.charsWritten;
}
- private static final String PROTOCOL_VERSION = "1.0";
+ private static final String PROTOCOL_VERSION = "1.1";
+
+ private static final String NEXT_MAJOR_VERSION_SCHEDULED = null;
private void writeRelays(List<SummaryDocument> relays, PrintWriter pw) {
- String header = "{\"version\":\"" + PROTOCOL_VERSION
- + "\",\n\"relays_published\":\"" + relaysPublishedString
- + "\",\n\"relays\":[";
+ String nextMajorVersionScheduledLine =
+ NEXT_MAJOR_VERSION_SCHEDULED == null
+ ? ""
+ : String.format("\"next_major_version_scheduled\":\"%s\",\n",
+ NEXT_MAJOR_VERSION_SCHEDULED);
+ String header = String.format("{\"version\":\"%s\",\n"
+ + "%s\"relays_published\":\"%s\",\n\"relays\":[",
+ PROTOCOL_VERSION, nextMajorVersionScheduledLine,
+ relaysPublishedString);
this.charsWritten += header.length();
pw.write(header);
int written = 0;
diff --git a/web/protocol.html b/web/protocol.html
index 9a46c9e..e55d167 100644
--- a/web/protocol.html
+++ b/web/protocol.html
@@ -135,8 +135,8 @@ If you want to be informed of upcoming protocol changes, subscribe to the
mailing list.
</p>
-<p>All responses contain a "version" string that indicates whether clients
-know whether they can parse the document or not.
+<p>All responses contain a <strong>"version"</strong> string that
+indicates whether clients can parse the document or not.
Version strings consist of a major and a minor version number.
The major version number is raised when previously required fields are
dropped or turned into optional fields, when request parameters or
@@ -147,12 +147,22 @@ If clients support the same major version given in a response but only a
lower minor version, they should be able to parse the document but may not
understand all fields.
If clients support a lower major version, they should not attempt to parse
-a document, because there may be backward-incompatible changes.
-The following versions have been used in the past six months:</p>
+a document, because there may be backward-incompatible changes.</p>
+
+<p>Responses may also contain the optional
+<strong>"next_major_version_scheduled"</strong> field that announces when
+the next major version is scheduled to be deployed.
+Clients should inform their users that they should upgrade to the next
+major protocol version before the provided date.</p>
+
+<p>The following versions have been used in the past six months or are
+scheduled to be deployed in the next months:</p>
<ul>
<li><strong>1.0</strong>: First assigned version number on August 31,
2014.</li>
+<li><strong>1.1</strong>: Added optional "next_major_version_scheduled"
+field on September 16, 2014.</li>
</ul>
</div> <!-- box -->
@@ -502,6 +512,18 @@ Onionoo protocol version string.
</li>
<li>
+<font color="blue"><b>next_major_version_scheduled</b></font>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to
+be deployed.
+Omitted if no major protocol changes are planned.
+<font color="blue">Added on September 16, 2014.</font>
+</p>
+</li>
+
+<li>
<b>relays_published</b>
<code class="typeof">string</code>
<span class="required-true">required</span>
@@ -665,6 +687,18 @@ Onionoo protocol version string.
</li>
<li>
+<font color="blue"><b>next_major_version_scheduled</b></font>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to
+be deployed.
+Omitted if no major protocol changes are planned.
+<font color="blue">Added on September 16, 2014.</font>
+</p>
+</li>
+
+<li>
<b>relays_published</b>
<code class="typeof">string</code>
<span class="required-true">required</span>
@@ -1450,6 +1484,18 @@ Onionoo protocol version string.
</li>
<li>
+<font color="blue"><b>next_major_version_scheduled</b></font>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to
+be deployed.
+Omitted if no major protocol changes are planned.
+<font color="blue">Added on September 16, 2014.</font>
+</p>
+</li>
+
+<li>
<b>relays_published</b>
<code class="typeof">string</code>
<span class="required-true">required</span>
@@ -1623,6 +1669,18 @@ Onionoo protocol version string.
</li>
<li>
+<font color="blue"><b>next_major_version_scheduled</b></font>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to
+be deployed.
+Omitted if no major protocol changes are planned.
+<font color="blue">Added on September 16, 2014.</font>
+</p>
+</li>
+
+<li>
<b>relays_published</b>
<code class="typeof">string</code>
<span class="required-true">required</span>
@@ -1828,6 +1886,18 @@ Onionoo protocol version string.
</li>
<li>
+<font color="blue"><b>next_major_version_scheduled</b></font>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to
+be deployed.
+Omitted if no major protocol changes are planned.
+<font color="blue">Added on September 16, 2014.</font>
+</p>
+</li>
+
+<li>
<b>relays_published</b>
<code class="typeof">string</code>
<span class="required-true">required</span>
@@ -2006,6 +2076,18 @@ Onionoo protocol version string.
</li>
<li>
+<font color="blue"><b>next_major_version_scheduled</b></font>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to
+be deployed.
+Omitted if no major protocol changes are planned.
+<font color="blue">Added on September 16, 2014.</font>
+</p>
+</li>
+
+<li>
<b>relays_published</b>
<code class="typeof">string</code>
<span class="required-true">required</span>
More information about the tor-commits
mailing list