Add Flatbuffers schema evolution rules to IDL (#2644)

api/flatbuffers/nanoapi.fbs

@@ -1,7 +1,69 @@
 /*
-  Flatbuffer schema for the Nano IPC API.
-  Please see https://google.github.io/flatbuffers/md__schemas.html for recommended schema evolution practices.
- */
+
+  Flatbuffers schema for the Nano IPC API.
+
+  This file contains IPC message definitions from which code and other artifacts are
+  generated.
+
+  Rules for editing this file:
+
+   - Only append or deprecate fields; never rearrange or remove fields. This ensures
+     binary backwards- and forwards compatibility.
+
+   - Renaming fields retain binary compatibility, but should still be considered
+     a breaking change in most cases. This is because the old name may be expected
+     in JSON messages and generated API accessors (which may lead to issues in dynamic
+     languages)
+
+   - Renaming a message is considered a breaking change, as the name appears in endpoints
+     and JSON message envelopes.
+
+   - Use 64-bit integer types only when the value fits in 2^53-1. This ensures exact
+     values in all supported bindings, including Javascript (which only supports the
+     double type) As an example, timestamps such as milliseconds-since-epoch can be
+     used safely.
+
+   - For integers larger than 2^53-1 where full precision is needed, use a string. Numbers
+     in strings are considered big int or big decimal, balances being a prominent example.
+
+   - Use the naming pattern SomeMessageName for requests, and SomeMessageNameResponse for
+     responses if an existing response type isn't available.
+
+   - Subscribe messages must be prefixed Topic and messages belonging to a subscription
+     must be prefixed Event. Using confirmations as an example, this means using the
+     message names TopicConfirmation and EventConfirmation respectively.
+
+   - Includes and multiple namespaces must not be used yet due to known issues with
+     language bindings.
+
+   - Do not use Flatbuffer structs, these are much harder to evolve and the benefits
+     are minor.
+
+   - Use the (required) attribute only when it's obvious it will never be optional in
+     the future. Required fields make it harder to obtain full compatibility.
+
+  Other considerations:
+
+   - If a message accrue many deprecations, consider making a minor-versioned message.
+     This should be done through nominal typing, i.e. a new message type with a suffix
+     indicating the version, like AccountWeight_v2_1. The response type can be an existing
+     type, but can also be versioned in the same manner. This naming pattern may be used
+     for endpoint mapping in the future, such as /api/v2_1/AccountWeight.
+
+   - If several messages need refactoring or improvements, a new API version should be
+     considered. This requires establishing a new endpoint (e.g. /api/v3)
+     New and old versions can co-exist.
+
+  Note that none of these rules apply to APIs considered internal, as these are versioned
+  by their enclosing binary. That is, all binaries (node, rpc, wallet, etc) using internal
+  APIs are expected to be upgraded at the same time and are thus versioned together. The
+  same relaxation applies to fields and messages considered "debug" or "experimental".
+
+  See also https://google.github.io/flatbuffers/md__schemas.html for recommended
+  schema evolution practices.
+
+*/
+
 namespace nanoapi;
 
 /** Returns the voting weight for the given account */