[Sync] Add ordinal_in_parent to SyncEntity/CommitResponse protobuf

chrome/browser/sync/protocol/sync.proto

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 //
 // Sync protocol for communication between sync client and server.
 
 // Update proto_value_conversions{.h,.cc,_unittest.cc} if you change
 // any fields in this file.
 
 syntax = "proto2";
@@ skipping 162 matching lines @@
   // Supplies a numeric position for this item, relative to other items with
   // the same parent.
   //
   // Present in both GetUpdatesResponse and CommitMessage.
   //
   // In a CommitMessage context, server implementations may choose whether
   // to compute a position based on this field or based on
   // |insert_after_item_id|.  Clients should set both values so that they
   // result in a consistent ordering regardless of which choice the server
   // makes.
+  //
+  // This is deprecated: clients should set |ordinal_in_parent|
+  // instead.  In the interim, clients should supply both

[ncarter (slow), 2012/02/09 01:30:58]

nit: The phrase "In the interim" made sense when the language was "This is
*being* deprecated", but it's a little temporally confusing as appears here.

+  // |ordinal_in_parent| and |position_in_parent| and continue to honor the
+  // |ordinal_in_parent| value returned in the CommitResponse.

[ncarter (slow), 2012/02/09 01:30:58]

There is no ordinal_in_parent value returned in the CommitResponse (and we don't
need one).

+  //
+  // When both |ordinal_in_parent| and |position_in_parent| are set,
+  // the first 8 bytes of |ordinal_in_parent| should be equal to
+  // the bytes of flip-sign-bit(|position_in_parent|) in big-endian order
+  // (MSB first).
   optional int64 position_in_parent = 15;

[ncarter (slow), 2012/02/09 01:30:58]

A draft of some possible language about the deprecation -- please revise/riff as
appropriate:

"Until such time as clients can be sure that all production server instances
fully support ordinal_in_parent, when committing, clients should set all three
position fields (position_in_parent, insert_after_item_id, and ordinal_in_parent
in commits), and continue to respect any position_in_parent values returned by
CommitResponses. Similarly, when ordinal_in_parent is absent in a GetUpdates,
and position_in_parent is present, clients should continue to honor the
position_in_parent value (possibly by transforming it as previously described)"

 
   // Contains the ID of the element (under the same parent) after which this
   // element resides. An empty string indicates that the element is the first
   // element in the parent.  This value is used during commits to specify
   // a relative position for a position change.  In the context of
   // a GetUpdatesMessage, |position_in_parent| is used instead to
   // communicate position.
   //
   // Present only in CommitMessage.
   //
   // This is being deprecated: clients should now explicitly set
   // an absolute |position_in_parent| value at commit time.  In the

[ncarter (slow), 2012/02/09 01:30:58]

This comment (which redirects to another deprecated feature) may create some
confusion. You might just want to redirect to the other comment.

   // interim, clients should supply both values and continue to honor
   // the |position_in_parent| value returned in the CommitResponse.
   optional string insert_after_item_id = 16;
 
   // Arbitrary key/value pairs associated with this item.
   // Present in both GetUpdatesResponse and CommitMessage.
   // Deprecated.
   // optional ExtendedAttributes extended_attributes = 17;
 
   // If true, indicates that this item has been (or should be) deleted.
@@ skipping 42 matching lines @@
   // c) Client tag - If client committed the item as unique
   //
   // May be present in CommitMessages for the initial creation of an entity.
   // If present in Commit updates for the entity, it will be ignored.
   //
   // Available in version 24+.
   //
   // May be returned in GetUpdatesMessage and sent up in CommitMessage.
   //
   optional string client_defined_unique_tag = 23;
+
+  // Supplies an ordinal for this item, relative to other items with the
+  // same parent.  Ordinals are ordered lexicographically bytewise.
+  // Ordinals must be a least 8 bytes (for backwards compatibility), and
+  // must not be all zeroes.
+  //
+  // Available in version 31+.
+  //
+  // Present in both GetUpdatesResponse and CommitMessage.
+  //
+  // In a CommitMessage context, server implementations may choose whether
+  // to compute a position based on this field, |position_in_parent|, or
+  // |insert_after_item_id|.  Clients should set all values so that they
+  // result in a consistent ordering regardless of which choice the server
+  // makes.
+  optional bytes ordinal_in_parent = 24;
 };
 
 // This message contains diagnostic information used to correlate
 // commit-related traffic with extensions-related mutations to the
 // data models in chromium.  It plays no functional role in
 // processing this CommitMessage.
 message ChromiumExtensionsActivity {
   // The human-readable ID identifying the extension responsible
   // for the traffic reported in this ChromiumExtensionsActivity.
   optional string extension_id = 1;
@@ skipping 149 matching lines @@
 // response is returned to the client indicating that the server has received
 // the request and has begun to clear data.
 message ClearUserDataMessage {
 }
 
 message ClearUserDataResponse {
 }
 
 message ClientToServerMessage {
   required string share = 1;
-  optional int32 protocol_version = 2 [default = 30];
+  optional int32 protocol_version = 2 [default = 31];
   enum Contents {
     COMMIT = 1;
     GET_UPDATES = 2;
     AUTHENTICATE = 3;
     CLEAR_DATA = 4;
   }
 
   required Contents message_contents = 3;
   optional CommitMessage commit = 4;
   optional GetUpdatesMessage get_updates = 5;
@@ skipping 47 matching lines @@
 
     // This name is the same as the non_unique_name field returned within the
     // SyncEntity message in GetUpdatesResponse.
     optional string non_unique_name = 8;
 
     optional string error_message = 9;
 
     // Last modification time (in java time milliseconds).  Allows the server
     // to override the client-supplied mtime during a commit operation.
     optional int64 mtime = 10;
+
+    // This value is the same as the ordinal_in_parent value returned within
+    // the SyncEntity message in GetUpdatesResponse.
+    optional bytes ordinal_in_parent = 11;
   }
 };
 
 message GetUpdatesResponse {
   // New sync entries that the client should apply.
   repeated SyncEntity entries = 1;
 
   // If there are more changes on the server that weren't processed during this
   // GetUpdates request, the client should send another GetUpdates request and
   // use new_timestamp as the from_timestamp value within GetUpdatesMessage.
@@ skipping 132 matching lines @@
   optional string store_birthday = 6;
 
   optional ClientCommand client_command = 7;
   optional ProfilingData profiling_data = 8;
 
   // The data types whose storage has been migrated.  Present when the value of
   // error_code is MIGRATION_DONE.
   repeated int32 migrated_data_type_id = 12;
 };