Compatibility guarantees for updating Tarantool

[xuniq]

Fixes #2218
Deploy: https://develop.tarantool.io/en/doc/gh-2218-compatibility/release/compatibility/

[patiencedaur]

Left a number of language-related comments. I might not fully understand the meaning of some phrases, I only look at the language.

[Totktonada]

I'm going to update the release policy with the following changes:

Patch

$ diff -u new-release-policy-v6.md new-release-policy-v7-wip.md
--- new-release-policy-v6.md	2022-03-05 16:31:16.197584906 +0300
+++ new-release-policy-v7-wip.md	2022-03-29 18:04:07.466683496 +0300
@@ -126,16 +126,33 @@
   error, but starts doing something useful, the change is considered
   compatible.
 
-  A room for new functionality is still here: we can add new options, add more
-  fields to a returning table, add more returning values (multireturn).
+  A room for new functionality is still here: we can add new arguments to the
+  end and options (fields in a table argument), add more fields to a returning
+  table, add more returning values (multireturn).
 
   Adding a new built-in module or a new global value is considered as the
   compatible change.
 
-  Adding a new metamethod to an existing metatable is okay if it is not listed
-  in the Lua Reference Manual. Otherwise it should be proven that it may not
-  broke any meaningful code (so, mathematical operations may generally be added
-  as well as `__lt` / `__le`; but not `__eq`).
+  Adding a new field to an existing metatable is okay if it is not listed in the
+  Lua 5.1 Reference Manual. Otherwise it should be proven that it may not broke
+  any meaningful code.
+
+  Examples of what is okay:
+
+  - Add `__pairs`, `__ipairs` to a metatable of a userdata/cdata (because it is
+    not from Lua 5.1 and because userdata/cdata has no default behaviour for
+    `pairs()` and `ipairs()` calls).
+  - Add or extend `__lt`, `__le` metamethod (if the attempt to use `<`, `<=`
+    and so on leads to an error before the change -- had no defined behaviour).
+  - Extend existing `__eq` metamethod implementation for a case, where it leads
+    to en error before the change.
+
+  Examples of NOT compatible changes:
+
+  - Add `__pairs`, `__ipairs` to a metatable of a table (because it already has
+    its own behaviour before the change).
+  - Add `__eq` metamethod if it was not defined (default behaviour is defined
+    for any pair of Lua objects).
 
 * **Backward compatibility (SQL code)**
 
@@ -149,6 +166,10 @@
   - Add a new built-in function.
   - Add a new system table that starts from underscore.
   - Add a new collation.
+  - Add an implicit or explicit cast rule for a set of operations {X} and a list
+    of types [Y] if [operation from {X}]([list of values of [Y] types]) is not
+    implemented before the change (raising an error).
+  - Change order of tuples in `SELECT`'s resultset if `ORDER BY` is not specified.
 
   Technically those changes may break a working code in case of a name clash,
   but the probability of this situation is considered as negligible. (We can
@@ -156,8 +177,7 @@
 
   Examples of NOT compatible changes:
 
-  - Change how data is stored in the database.
-  - Change how type arithmetic works (say, implicit casting rules).
+  - Change result of working implicit or explicit cast.
   - Change of a literal type.
 
 * **Backward compatibility (C code)**

Please, reflect the changes in this document.

[Totktonada]

I see that some changes are already fully or partially applied. Please, compare it carefully.

[Totktonada]

It is not exactly same as the original phrase:

The upgrade does not cause downtime (if the application does not lean on internal schema representation).

If an application leans on something internal, this internal thing may be changed with the upgrade, so the application will not work (or will work incorrectly) and, yep, it may lead to a downtime.

I would propose something like so:

An application should not lean on internal schema representation, because it may be changed at the upgrade.

I guess it is enough.

[Totktonada]

I looked over the proposed document and it don't see mistakes in facts.

I attached planned update of guarantees regarding Lua and SQL. It would be quite good to reflect it.

Aside of this I have no objections.