Управление версиями
Разделение API на несколько версий необходимо для совершенствования без ущерба обратной совместимости. С одной стороны, постоянно возникают новые потребности и необходимо вносить изменения, с другой стороны, любое изменение программного интерфейса может нарушить работу существующих плагинов. Для решения этой дилеммы история развития API делится на версии: в определённый момент разработка очередной версии прекращается, интерфейс фиксируется, дальнейшее развитие продолжается в рамках следующей версии. Какие бы изменения ни вносились в будущем, разработанный под зафиксированную версию плагин будет исправно функционировать до тех пор, пока эта версия не перестанет поддерживаться.
Жизненный цикл версий
Большие LTS-версии (от Long-Term Support) выпускаются примерно раз в два года и поддерживаются около четырёх лет. Между ними выпускаются промежуточные preview-версии, они выходят каждые три месяца и поддерживаются в течение 3 версий iikoRMS. Таким образом, в каждый момент времени поддерживаются две последние выпущенные LTS-версии, три последние выпущенные preview-версии (либо две, если за предыдущие 9 месяцев вышла LTS-версия), а также для ознакомления доступна разрабатываемая LTS-версия.
LTS-версии нумеруются по порядку целыми числами — V1, V2, V3, V4, V5, V6 и так далее. Preview-версии являются копиями промежуточных состояний разрабатываемой LTS-версии, поэтому содержат в названии номер разрабатываемой LTS-версии и нумеруются по порядку с префиксом «Preview», например, во время разработки V9 будут выходить версии V9Preview1, V9Preview2 и так далее до V9Preview7, после чего выйдет сама V9.
График выпуска
После выпуска очередной LTS-версии роли перераспределяются следующим образом:
- поддержка устаревшей версии прекращается;
- версия, которая была стабильной, объявляется устаревшей;
- версия, разработка которой завершилась, фиксируется и становится стабильной;
- появляется новая разрабатываемая версия.
Цикл preview-версий чуть проще:
- поддержка устаревшей preview-версии прекращается;
- актуальная preview-версия объявляется устаревшей. Если актуальных preview-версий было две, то устаревшей объявляется более старая из них;
- копия текущего состояния разрабатываемой LTS-версии выпускается как новая актуальная preview-версия.
Выбор версии
По умолчанию рекомендуется использовать стабильную LTS-версию, это позволит минимизировать трудозатраты по миграции на новые версии API. Если необходимы новые функции, ещё недоступные в LTS-версиях, рекомендуется использовать актуальную preview-версию, в этом случае придётся мигрировать между preview-версиями каждые 3-6 месяцев, пока не выйдет очередная LTS-версия. Разработку под версии, объявленные устаревшими, лучше даже не начинать, это бесперспективно, эти версии поддерживаются лишь для обратной совместимости на период, когда новая версия API уже вышла, а плагины на неё пока не перешли. Разрабатываемую версию использовать не рекомендуется, поскольку её интерфейс ещё не зафиксирован, обратная совместимость не обеспечивается, возможны любые изменения. Эта версия доступна для изучения нововведений и раннего начала разработки плагина для будущей версии API, чтобы к моменту её выпуска иметь готовый или почти готовый плагин, предоставляющий новые возможности.
Версия API, под которую разработан плагин, определяется по версии интерфейса IFrontPlugin, который он реализует.
Например, если плагин ссылается на сборку Resto.Front.Api.V6.dll и реализует интерфейс IFrontPlugin из этой сборки, это V6-плагин.
Предполагается, что V6-плагин использует программный интерфейс версии V6.
Тем не менее, при необходимости плагин может одновременно использовать все поддерживаемые версии API.
Учитывая, что начиная с V6 пространства имён не содержат номер версии API, во избежание коллизий между одноимёнными типами из разных сборок придётся использовать extern alias.
Например, чтобы из V6-плагина получить доступ к операции, которая появилась только в V7Preview2, помимо обычной ссылки на V6 необходимо добавить ссылку V7Preview2 с указанием alias V7Preview2, и затем из PluginContext.Services извлечь сервис V7Preview2::Resto.Front.Api.IOperationService.
Механизм PackageReference поддерживает extern alias начиная с Visual Studio 2019 16.7.
Важно: не следует одновременно реализовывать интерфейсы IFrontPlugin разных версий, такой плагин не будет загружен.
Соответствие версий iikoRMS и версий API
| Версия | Выпуск | Удаление |
|---|---|---|
| V1 | 3.1 | 3.8 |
| V2 | 3.3 | 4.3 |
| V3 | 3.8 | 5.4 |
| V4 | 4.3 | 7.0 |
| V5 | 5.4 | 8.0 |
| V6Preview4 | 6.41 | 7.0 |
| V6Preview5 | 6.4 | 7.1 |
| V6 | 7.0 | |
| V7Preview1 | 7.1 | 7.4 |
| V7Preview2 | 7.3.52 | 7.4 |
| V7Preview3 | 7.3 | 7.5 |
| V7Preview4 | 7.4 | 7.6 |
| V7Preview5 | 7.5 | 7.7 |
| V7Preview6 | 7.6 | 7.9 |
| V7Preview7 | 7.7 | 8.53 |
| V7 | 7.9 | 9.5 |
| V8Preview1 | 8.0 | 8.2 |
| V8Preview2 | 8.1 | 8.3 |
| V8Preview3 | 8.2 | 8.4 |
| V8Preview44 | 8.3 | 8.6 |
| V8Preview5 | 8.4 | 8.7 |
| V8Preview6 | 8.5 | 8.8 |
| V8Preview7 | 8.6 | 8.9 |
| V8 | 8.7 | 10.3 |
| V9Preview1 | 8.8 | 9.1 |
| V9Preview2 | 8.9 | 9.2 |
| V9Preview3 | 9.0 | 9.3 |
| V9Preview4 | 9.1 | 9.4 |
| V9Preview5 | 9.2 | 9.5 |
| V9Preview6 | 9.3 | 9.6 |
| V9Preview7 | 9.4 | 9.7 |
| V9 | 9.5 | |
| V10Preview1 | 9.6 | 9.9 |
| V10Preview2 | 9.7 | 10.0 |
| V10Preview3 | 9.8 | 10.1 |
| V10Preview4 | 9.9 | 10.2 |
| V10Preview5 | 10.0 | 10.3 |
| V10Preview6 | 10.1 | 10.4 |
| V10Preview7 | 10.2 | 10.5 |
| V10 | 10.3 |
1 Версия V6Preview4 была экспериментальной, она выпущена в начале цикла разработки iikoRMS 6.4. Кроме того, были пропущены V6Preview6 и V6Preview7, вместо них сразу вышла LTS-версия V6.
2 Версия V7Preview2 выпущена с опозданием в 7.3.5 (вместо 7.2).
3 Поддержка версии V7Preview7 была продлена до 8.6 включительно из-за проблем с автообновлением плагинов с V7Preview7 на V7.
4 Срок жизни Preview-версий начиная с V8Preview4 увеличен на одну версию iikoRMS.
Начиная с версии iikoRMS 8.5 цикл поддержки Preview-версий увеличивается: версия V8Preview4, которая была выпущена в 8.3, будет удалена лишь в 8.6, т.е. поддерживается в 8.3, 8.4, 8.5.
Обратная совместимость
Обратная совместимость предполагает гарантию того, что плагин, разработанный под определённую версию API, будет одинаково работать с любыми версиями iikoRMS, поддерживающими эту версию API.
Программная совместимость
Программная совместимость запрещает изменения в публичном интерфейсе — необходимо фиксировать структуры данных, сигнатуры методов и прочее. Понятно, что если удалить какой-то публичный класс или метод, плагин перестанет компилироваться с новым SDK, а скомпилированный под старый SDK будет падать во время работы (TypeLoadException, MissingMethodException и т. п.). Возможны и не столь очевидные нарушения обратной совместимости. Однако, если не брать в расчёт экзотические случаи, на практике добавление нового класса, свойства или метода вполне может оказаться безопасным. Зато появляется возможность начать использовать новые функции, не дожидаясь очередного релиза. С учётом этого сейчас принята такая политика:
- в LTS-версиях никаких изменений после релиза, ибо every public change is a breaking change,
- в preview-версиях возможны почти наверное обратно совместимые изменения публичного интерфейса.
Изменения в поведении
В общем случае, изменения в поведении выпущенных версий API не допускаются. Если какая-то функция в определённых условиях работала, она и продолжит работать, а если не работала, она продолжит точно так же не работать. Исключение — деструктивные сценарии использования API, когда последствия хуже нарушения обратной совместимости. Например, если из-за уязвимости в API ошибочные действия плагина могли привести к повреждению данных или остановке работы приложения iikoFront, то в API появится соответствующая защита. Это не будет считаться изменением поведения, поскольку корректно работающие плагины не заметят никаких изменений.
Срок поддержки
Под продолжительностью поддержки определённой версии API понимается период, в течение которого выпускаются обновления iikoRMS, поддерживающие эту версию API. В самом продукте iikoRMS нет календарного ограничения на возможность использования той или иной версии API. Все версии API, поддерживаемые конкретной сборкой iikoRMS, поддерживаются ею бессрочно. Таким образом, если пользователь iikoRMS не обновляется, он теоретически может продолжать использовать старые плагины как угодно долго. Однако, на практике пользователь вынужден обновлять iikoRMS ради поддержки изменений в законодательстве, новых функций и исправленных ошибок, а это значит, что и разработчик плагина должен своевременно выпускать обновления плагина, совместимые с новыми версиями API.