Версионирование Electron

Подробный обзор нашей политики и реализации версионирования.

Начиная с версии 2.0.0, Electron следует спецификации SemVer. Следующая команда установит последнюю стабильную сборку Electron:

npm install --save-dev electron

yarn add --dev electron

Для обновления существующего проекта до использования последней стабильной версии:

npm install --save-dev electron@latest

yarn add --dev electron@latest

Схема версионирования​

Ниже приведены несколько основных изменений по сравнению с нашей стратегией 1.x. Каждый из них предназначен для удовлетворения потребностей и приоритетов разработчиков/поддерживающего персонала и разработчиков приложений.

1. Строгое использование спецификации SemVer
2. Внедрение совместимых с semver -beta тегов
3. Внедрение стандартных сообщений о внесенных изменениях
4. Четко определенные ветки стабилизации
5. Ветка main не имеет версирования; только ветки стабилизации содержат информацию о версии

Мы подробно рассмотрим, как работает ветвление Git, как работает маркировка npm, что должны ожидать разработчики и как можно перенести изменения.

SemVer​

Ниже приведена таблица, в которой явно сопоставлены типы изменений с соответствующей категорией SemVer (например, Major, Minor, Patch).

Для получения дополнительной информации см. спецификацию Semantic Versioning 2.0.0.

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

Ветки стабилизации​

Ветки стабилизации — это ветки, которые существуют параллельно с main, принимая только выбранные исправления, связанные с безопасностью или стабильностью. Эти ветки никогда не сливаются обратно в main.

Начиная с Electron 8, ветки стабилизации всегда являются основными версиями и называются по следующему шаблону $MAJOR-x-y, например 8-x-y. До этого мы использовали дополнительные версии и называли их как $MAJOR-$MINOR-x, например 2-0-x.

Мы допускаем одновременное существование нескольких веток стабилизации, по одной для каждой поддерживаемой версии. Более подробную информацию о поддерживаемых версиях см. в документе Electron Releases.

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

Выпуск бета-версий и исправление ошибок​

Разработчики хотят знать, какие выпуски являются безопасными для использования. Даже на первый взгляд безобидные функции могут привести к регрессии в сложных приложениях. В то же время, блокировка на определённой версии опасна, поскольку вы игнорируете исправления безопасности и исправления ошибок, которые могли появиться после вашей версии. Наша цель состоит в том, чтобы разрешить следующие стандартные диапазоны semver в package.json:

• Используйте ~2.0.0 для принятия только исправлений, связанных со стабильностью или безопасностью, в вашем выпуске 2.0.0.
• Используйте ^2.0.0 для принятия неразрывной достаточно стабильной работы функций, а также исправлений безопасности и ошибок.

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

В любом случае вам периодически придётся обновлять версию в вашем package.json , так как разрывные изменения — неизбежная часть жизни Chromium.

Процесс следующий:

1. Все новые ветки основных и дополнительных версий начинаются с бета-серии, обозначенной тегами предварительного выпуска SemVer beta.N, например 2.0.0-beta.1. После первой бета-версии последующие бета-версии должны удовлетворять всем следующим условиям:
   1. Изменения обратной совместимы с API (разрешены устаревшие функции)
   2. Риск, связанный с соблюдением нашего графика стабильности, должен быть низким.
2. Если после выхода бета-версии необходимо внести разрешенные изменения, они применяются, и тег предварительного выпуска увеличивается, например 2.0.0-beta.2.
3. Если определённая бета-версия считается в целом стабильной, она будет повторно выпущена как стабильная сборка, меняя только информацию о версии. Например, 2.0.0. После первой стабильной версии все изменения должны быть обратной совместимыми исправлениями ошибок или безопасности.
4. Если впоследствии потребуются исправления ошибок или исправления безопасности, они применяются, и дополнительная версия увеличивается, например 2.0.1.

В частности, вышесказанное означает:

1. Принятие изменений, не нарушающих API, до 3-й недели цикла бета-тестирования допустимо, даже если эти изменения могут потенциально привести к умеренным побочным эффектам.
2. Принятие изменений с флагами функций, которые не изменяют существующие пути кода, во многих точках цикла бета-тестирования допустимо. Пользователи могут явно включить эти флаги в своих приложениях.
3. Принятие функций любого рода после 3-й недели цикла бета-тестирования недопустимо без веской причины.

Для каждой перемены основных и дополнительных версий вы должны ожидать примерно следующее:

2.0.0-beta.1
2.0.0-beta.2
2.0.0-beta.3
2.0.0
2.0.1
2.0.2

Пример жизненного цикла на картинках:

• Создаётся новая ветка выпуска, которая включает в себя последний набор функций. Она публикуется как 2.0.0-beta.1.
• В мастер появляется исправление ошибки, которое можно перенести обратно во ветку выпуска. Исправление применяется, и публикуется новая бета-версия 2.0.0-beta.2.
• Бета-версия считается в целом стабильной и повторно публикуется как не-бета-версия под 2.0.0.
• Позже выявляется уязвимость нулевого дня, и для неё создаётся исправление. Мы переносим исправление в ветку 2-0-x и выпускаем 2.0.1.

Несколько примеров того, как различные диапазоны SemVer будут выбирать новые версии:

Процесс запроса переноса​

Все поддерживаемые ветки выпусков будут принимать внешние запросы на слияние для переноса исправлений, ранее объединённых в main, хотя это может быть в каждом случае индивидуально для некоторых более старых поддерживаемых веток. Все спорные решения по переносу веток выпусков будут решаться рабочей группой Releases Working Group в качестве пункта повестки на их еженедельном собрании на той неделе, когда запрос на слияние поднимается.

Флаги функций​

Флаги функций — это распространённая практика в Chromium и широко используются в среде разработки веб-приложений. В контексте Electron флаг функции или мягкая ветка должна обладать следующими свойствами:

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

Семантические коммиты​

Все запросы на слияние должны соответствовать спецификации Conventional Commits, которую можно кратко сформулировать следующим образом:

• Коммиты, которые приведут к увеличению версии SemVer major, должны начинаться в теле с BREAKING CHANGE:.
• Коммиты, которые приведут к увеличению версии SemVer minor, должны начинаться с feat:.
• Коммиты, которые приведут к увеличению версии SemVer patch, должны начинаться с fix:.

Репозиторий electron/electron также требует слияния с объединением, поэтому вам нужно только убедиться, что ваш запрос на слияние имеет правильный префикс названия.

Версионированный main ветвь​

• Ветка main всегда будет содержать следующую основную версию X.0.0-nightly.DATE в своей package.json.
• Ветви релизов никогда не сливаются обратно в main.
• Ветви релизов содержат правильную версию в своей package.json.
• Как только ветвь релиза будет создана для основной версии, main должна быть повышена до следующей основной (то есть main всегда версируется как следующая теоретическая ветвь релиза).

Историческая версия (Electron 1.X)​

Версии Electron < 2.0 не соответствовали спецификации SemVer: основные версии соответствовали изменениям API для конечных пользователей, второстепенные версии — основным выпускам Chromium, а версий исправлений — новым функциям и исправлениям ошибок. Хотя это удобно для разработчиков, интегрирующих новые функции, это создает проблемы для разработчиков клиентских приложений. Циклы тестирования качества крупных приложений, таких как Slack, Teams, Skype, VS Code и GitHub Desktop, могут быть длительными, а стабильность — высокожелаемым результатом. Существует высокий риск принятия новых функций во время попытки исправить ошибки.

Вот пример стратегии 1.x:

Приложение, разработанное с использованием 1.8.1 не может принять исправление 1.8.3 ошибок без либо интеграции новой 1.8.2 функции, либо путем обратной перепортировки исправления и поддержания новой ветви релиза.