Версии расширений

Версии расширений

У большинства программ есть номер версии. Номера версий служат нескольким важным целям:

• Связывает двоичный файл с определённым состоянием исходного кода
• Позволяет определить ожидаемый набор функций
• Позволяет определить состояние API
• Позволяет эффективно обрабатывать сообщения об ошибках (например, ошибка #1337 была введена в версии v3.4.5 )
• Позволяет определить хронологический порядок выпусков (например, версия v1.2.3 старше, чем v1.2.4 )
• Позволяет определить ожидаемую стабильность (например, v0.0.1 вероятно не очень стабильна, тогда как v13.11.0 вероятно стабильна)

Так же как и сам DuckDB, расширения DuckDB имеют свои собственные номера версий. Для обеспечения согласованной семантики этих номеров версий в различных расширениях, ядро DuckDB (Core Extensions) использует схему версионирования, которая предписывает, как должны версионироваться расширения. Схема версионирования для Core Extensions состоит из 3 разных уровней стабильности: нестабильная, предварительная и стабильная. Давайте рассмотрим каждый из 3-х уровней и опишем их формат:

Нестабильные расширения

Нестабильные расширения — это расширения, которые не могут (или не хотят) гарантировать текущую стабильность или свои цели по достижению стабильности. Нестабильные расширения помечены короткой хеш-суммой git расширения.

Например, на момент написания этой статьи, версия расширения vss — это нестабильное расширение версии 690bfc5.

Что следует ожидать от расширения, у которого номер версии в формате нестабильный?

• Состояние исходного кода расширения можно найти, посмотрев хеш в репозитории расширения
• Функциональность может изменяться или полностью удаляться с каждым релизом
• API этого расширения может меняться с каждым релизом
• Это расширение может не следовать структурированному циклу релизов, новые (разрушающие) версии могут быть выпущены в любое время

Расширения предварительной версии

Расширения предварительной версии — это следующий шаг по сравнению с нестабильными расширениями. Они помечены номером версии в формате SemVer, более конкретно, в формате v0.y.z. В семантическом версионировании версии, начинающиеся с v0, имеют особое значение: они указывают на то, что более строгие семантики обычных (>v1.0.0) версий пока не применяются. В основном это означает, что расширение стремится стать стабильным расширением, но пока не до конца.

Например, на момент написания этой статьи, версия расширения delta — это расширение предварительной версии v0.1.0.

Что следует ожидать от расширения, у которого номер версии в формате предварительной версии?

• Расширение компилируется из исходного кода, соответствующего тегу.
• Применяются семантики SemVer. Подробности см. в спецификации SemVer.
• Расширение следует циклу релизов, где новые функции тестируются в ночных сборках перед объединением в релиз и публикацией в репозитории core.
• Должны быть доступны заметки к релизу, описывающие, что было добавлено в каждом релизе, чтобы упростить понимание различий между версиями.

Стабильные расширения

Стабильные расширения — это последний этап стабильности расширений. Это обозначается использованием стабильной SemVer формата vx.y.z, где x>0.

Например, на момент написания этой статьи, версия расширения parquet — это стабильное расширение версии v1.0.0.

Что следует ожидать от расширения, у которого номер версии в формате стабильный? В основном то же самое, что и у расширений предварительной версии, но теперь применяются более строгие семантики SemVer: API расширения теперь должно быть стабильным и будет изменяться только несовместимыми способами, когда будет изменен основной номер версии. Подробности см. в спецификации SemVer.

Цикл выпуска предварительных и стабильных расширений ядра

В общем случае, цикл выпуска расширений зависит от уровня их стабильности. Расширения нестабильные часто синхронизируются с циклом выпуска DuckDB, но также могут быть тихо обновлены между выпусками DuckDB. Расширения предварительной версии и стабильные следуют своему собственному циклу выпуска. Они могут или не могут совпадать с выпусками DuckDB. Чтобы узнать больше о цикле выпуска конкретного расширения, обратитесь к документации или странице GitHub соответствующего расширения. В целом, расширения предварительной версии и стабильные будут документировать свои релизы как релизы GitHub, пример которых вы можете увидеть в расширении delta.

Наконец, существует небольшое исключение: все расширения встроенные просто следуют циклу выпуска DuckDB.

Ночные сборки

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

Ночные сборки расширений немного сложны, так как в настоящее время двоичные файлы расширений DuckDB тесно связаны с одной версией DuckDB. Из-за этой тесной связи существует потенциальный риск комбинаторного взрыва. Поэтому не все комбинации ночной сборки расширения и ночной сборки DuckDB доступны.

В целом, есть 2 способа использования ночных сборок: используя ночную сборку DuckDB и используя стабильную сборку DuckDB. Давайте разберёмся в различиях между ними:

Из стабильной сборки DuckDB

В большинстве случаев пользователи будут заинтересованы в ночной сборке конкретного расширения, но не обязательно захотят переключаться на использование ночной сборки самого DuckDB. Это позволяет использовать конкретную функцию bleeding-edge, ограничивая воздействие на нестабильный код.

Для этого расширения ядра обычно регулярно публикуют сборки в core_nightly репозитории. Давайте рассмотрим пример:

Сначала установим стабильную сборку DuckDB.

Затем мы можем установить и загрузить ночное расширение так:

INSTALL aws FROM core_nightly;
LOAD aws;

В этом примере мы используем последнюю ночную сборку расширения aws с последней стабильной версией DuckDB.

Из ночной сборки DuckDB

Когда DuckDB CI создаёт ночную сборку самого DuckDB, двоичные файлы распространяются с набором расширений, которые закреплены на конкретной версии. Эта версия расширения будет протестирована для этой конкретной сборки DuckDB, но может не быть последней тестовой сборкой. Давайте рассмотрим пример:

Сначала установим ночную сборку DuckDB. Затем мы можем установить и загрузить расширение aws как ожидается:

INSTALL aws;
LOAD aws;

Обновление расширений

DuckDB имеет специальную команду, которая автоматически обновит все расширения до последней версии. Вывод будет предоставлять пользователю информацию о том, какие расширения были обновлены до/с какой версии. Например:

UPDATE EXTENSIONS;

Обратите внимание, что DuckDB будет искать обновления в исходном репозитории для каждого расширения. Таким образом, если расширение было установлено из core_nightly, оно будет обновлено с последней ночной сборкой.

Команда обновления также может быть предоставлена с перечнем конкретных расширений для обновления:

UPDATE EXTENSIONS (httpfs, azure);

Целевая версия DuckDB

В настоящее время, при компиляции расширений, они привязаны к определенной версии DuckDB. Это означает, что, например, бинарный файл расширения, скомпилированный для версии v0.10.3, не будет работать для версии v1.0.0. В большинстве случаев это не вызовет никаких проблем и полностью прозрачно; DuckDB автоматически позаботится об установке правильного бинарного файла для своей версии. Для разработчиков расширений это означает, что они должны обеспечивать создание новых бинарных файлов всякий раз, когда выпускается новая версия DuckDB. Однако обратите внимание, что DuckDB предоставляет шаблон расширения, который делает это довольно простым.