Гарантии совместимости

Обратная совместимость гарантируется между всеми версиями в одной release series. Она также желательна, но не гарантируется между разными сериями релизов (при изменении старшего номера версии). Пререлизы и релизы одной серии совместимы во всех смыслах, описанных ниже (любой релиз с любым релизом):

• Пререлизы и релизы последовательных серий совместимы по формату данных, бинарному протоколу и протоколу репликации.
• Не дается никаких гарантий совместимости между пререлизами/релизами непоследовательных серий релизов, если обратное не указано в примечаниях к релизу.
• Не дается никаких гарантий совместимости между альфа/бета-версиями, а также между альфа/бета-версиями и пререлизами/релизами даже в пределах одной серии.

Любой более новый релиз (его среда выполнения) обратно совместим с любым более старым. Это означает, что более новый релиз может работать с данными (*.xlog, *.snap, *.vylog, *.run) более старого релиза. Вся функциональность более старого релиза работает в этой конфигурации. Такая же совместимость поддерживается и между release series.

Попытка использовать новую функциональность приводит к одному из следующих вариантов:

• Попытка успешна.
• Выводится сообщение об ошибке, связанной со старым форматом данных. Ошибка не приводит к недоступности сервиса или повреждению данных. Избежать появления этого сообщения можно, обновив формат данных экземпляра с помощью вызова box.schema.upgrade(). Этот вызов включает всю функциональность нового релиза (при условии, что все экземпляры набора реплик работают на одной версии Tarantool).

Все запросы бинарного протокола, работающие в более старом релизе, продолжают работать в более новом. Ответы имеют тот же формат, но отображения (mappings) могут содержать поля, отсутствовавшие в более старом релизе.

Клиент net.box более старого релиза может работать с сервером, на котором запущен более новый релиз. Однако функции net.box, добавленные в более новом релизе, работать не будут. Клиент net.box более нового релиза полностью работоспособен с сервером, на котором запущен более старый релиз. Однако будут работать только те функции, которые реализованы в более старом релизе.

Экземпляр, работающий на более новом релизе, может выступать в роли:

• upstream (мастера) для экземпляра с более старым релизом
• downstream (реплики) без обновления схемы базы данных.

Обновление схемы базы данных (box.schema.upgrade()) должно выполняться, когда все экземпляры набора реплик работают на одной версии Tarantool. Приложение не должно полагаться на внутреннее представление схемы, так как оно может измениться при обновлении.

Если код выполняется на более старом релизе, он будет работать с тем же результатом на более новом. Однако учитывается только осмысленный код. Если код вызывает ошибку, но при этом начинает делать что-то полезное, такое изменение считается совместимым.

Остаётся возможность для добавления новой функциональности: добавление новых параметров (полей в табличном аргументе), новых аргументов в конец списка, дополнительных полей в возвращаемую таблицу и дополнительных возвращаемых значений (множественный возврат).

Добавление нового встроенного модуля или нового глобального значения считается совместимым изменением.

Добавление нового поля в существующую метатаблицу допустимо, если это поле не описано в Справочном руководстве по Lua 5.1. В противном случае необходимо доказать, что это не сломает какой-либо осмысленный код.

Примеры совместимых изменений:

• Добавление __pairs, __ipairs в метатаблицу объекта userdata/cdata. Эти поля отсутствуют в Lua 5.1, а у userdata/cdata нет поведения по умолчанию для вызовов pairs() и ipairs().
• Добавление или расширение метаметода __lt или __le (если попытка использования <, <= и т.д. приводила к ошибке до изменения).
• Расширение существующей реализации метаметода __eq (если попытка его использования приводила к ошибке до изменения).

Примеры несовместимых изменений:

• Добавление __pairs, __ipairs в метатаблицу таблицы (до изменения у неё уже определено поведение по умолчанию).
• Добавление метаметода __eq (у любой пары Lua-объектов уже определено поведение по умолчанию).

Если запрос выполняется на более старом релизе, он будет работать с тем же результатом на более новом (за исключением запросов, которые всегда приводят к ошибке).

Примеры совместимых изменений:

• Добавление нового ключевого слова.
• Добавление нового типа.
• Добавление новой встроенной функции.
• Добавление новой системной таблицы, имя которой начинается с подчёркивания.
• Добавление нового правила сортировки (collation).
• Добавление правила неявного или явного приведения типов для набора операций {X} и списка типов [Y], если [операция из {X}](/[список значений типов /[Y/]/]) не была реализована до изменения.
• Изменение порядка кортежей в результирующей выборке SELECT, если не указан ORDER BY.

Технически эти изменения могут сломать некоторый работающий код в случае конфликта имён, но вероятность этого пренебрежимо мала.

Примеры несовместимых изменений:

• Изменение результата работающего неявного или явного приведения типов.
• Изменение типа литерала.

Если модуль или хранимая процедура на C работает на более старом релизе, она будет работать с тем же результатом на более новом.

Допустимо добавление новой функции или структуры в публичный C API. Функция должна использовать один из префиксов Tarantool (box_, fiber_, luaT_, luaM_ и т.д.) или некоторый новый префикс.

Символ из используемой библиотеки не должен экспортироваться напрямую, так как библиотека может использоваться в модуле самостоятельно, и конфликт может привести к проблемам. Исключение: когда экспортируется весь публичный API библиотеки (как для libcurl).

Не следует добавлять новые функции или структуры с префиксами lua_ и luaL_. Эти префиксы предназначены для среды выполнения Lua. Используйте luaT_ для функций, специфичных для Tarantool, и luaM_ для функций общего назначения.