[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [onionoo/master] Add next_major_version_scheduled field.



commit f04a923ecccb1dbcdcfbe3cb7da4e24a331a1422
Author: Karsten Loesing <karsten.loesing@xxxxxxx>
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>

_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits