Предложение по политике заката для действия на GitHub

Я являюсь текущим сопровождающим GitHub Action для проверки орфографии в файлах в репозитории GitHub. Действие «GitHub Spellcheck Action» (rojopolis/spellcheck-github-actions) выросло в популярности и используется в нескольких репозиториях GitHub, что означает, что изменения в программном обеспечении и его доступность стали значительными факторами в его жизненном цикле. В то же время, он основан на открытой и бесплатной инфраструктуре и поддержке, поэтому я решил, что пришло время ввести политику заката.

В этом посте я постараюсь изложить обоснование политики заката. Если вас не интересует обоснование, а интересует только предложение, просто перейдите к «Предложению о политике заката» ниже.

GitHub Spellcheck Action основан на образе Docker. Время от времени я удаляю образы, которые стали_старыми_. Ранее я просто делал это, но мне всегда казалось, что это не совсем правильный подход — поэтому, поразмыслив, я пришел к выводу, что мне нужно разработать предложение по политике заката. Это мысли и идеи, формирующие обоснование предложения.

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

Немного статистики по репозиторию:

• 83 звезды
• 32 форка
• 13 вкладчиков — в основном случайные вкладчики
• 440+ зависимых — несколько из них являются моими форками для PRs для выгрузки использованной версии этого действия, подробнее об этом позже

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

Как уже было сказано, я не являюсь первоначальным автором этого репозитория, я просто текущий сопровождающий. У меня были некоторые идеи по улучшению, так как я был активным пользователем, делал много орфографических ошибок и использовал экшен для 20+ репозиториев для преимущественно общедоступных спецификаций. Когда действия GitHub появились на сцене, я был очень рад принять их использование и, конечно, был заинтересован в обратной связи для моих сборок.

Когда я взял на себя сопровождение, я хотел переместить действие, чтобы больше полагаться на часть Docker для ускорения времени выполнения, уменьшая время сборки, так как образ Docker собирался при каждом запуске. Первый релиз, основанный на репозитории Docker, был версии 0.5.0, последний релиз — 0.23.2. Обратная связь по сборке важна, но она также должна приходить как можно быстрее, и использование предварительно собранного образа Docker вместо сборки «на лету» кажется разумным подходом.

Статистика по релизам:

• Всего 28 релизов
• 4 релиза без сборки образов Docker (0.1.0—0.4.0)
• 24 релиза с использованием предварительно собранных образов Docker

Однако это создает несколько других проблем:

• Артефакты становятся устаревшими
• Сопровождение версионных образов

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

Все образы Docker обслуживаются с DockerHub. По мере выпуска и загрузки новых образов, старые образы становятся все менее популярными, о чем свидетельствует недостаток скачиваний/загрузок.

В настоящее время образы удаляются вручную, и именно здесь политика заката будет играть важную роль, поскольку удаление образа для определенной версии может сделать данную живую конфигурацию бесполезной. Я рекомендую Dependabot для автоматического обслуживания, и Renovate также может быть альтернативой, но не все пользователи используют эти инструменты.

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

Статистика по открытым мною PR:

• Около 5 открытых PR для обновления конфигураций действий.
• 1 использует версию 0.11.0
• 1 использует версию 0.13.0
• 2 использует версию 0.14.0
• 1 использует версию 0.16.0.

Есть еще много потенциальной работы.

Если я проведу дополнительный поиск кода (я использую SourceGraph’s «Code Search», подробности см. в моем блоге), то можно получить интересную статистику по используемым версиям:

Существует множество репозиториев, которым не помешал бы PR и подсказка о том, как использовать Dependabot или Renovate. К счастью, похоже, что использование идет в ногу с релизами, и новые версии подхватываются и становятся ведущими.

Если мы посмотрим на образы Docker, извлеченные из DockerHub, мы увидим, что все образы извлекаются, но некоторые из них не извлекались в течение некоторого времени, а другие набирают обороты при внедрении.

zsh> hub-tool tag ls jonasbn/github-action-spellcheck --format json | jq 'sort_by(.LastPulled)| reverse' | jq -S --raw-output '.[] | [.Name, .LastPulled] | @tsv'
jonasbn/github-action-spellcheck:0.23.0 2022-05-07T08:10:01.439973Z
jonasbn/github-action-spellcheck:0.23.1 2022-05-07T04:08:52.108901Z
jonasbn/github-action-spellcheck:0.23.2 2022-05-07T04:08:52.108901Z
jonasbn/github-action-spellcheck:latest 2022-05-07T04:08:52.108901Z
jonasbn/github-action-spellcheck:0.21.1 2022-05-06T22:37:26.587984Z
jonasbn/github-action-spellcheck:0.20.0 2022-05-06T17:32:42.68943Z
jonasbn/github-action-spellcheck:0.22.1 2022-05-04T08:11:38.567402Z
jonasbn/github-action-spellcheck:0.22.0 2022-05-04T07:34:23.267566Z
jonasbn/github-action-spellcheck:0.13.0 2022-04-29T17:04:41.597812Z
jonasbn/github-action-spellcheck:0.14.0 2022-04-29T17:04:41.597812Z
jonasbn/github-action-spellcheck:0.17.0 2022-03-26T16:53:51.628996Z
jonasbn/github-action-spellcheck:0.21.0 2022-01-25T07:18:17.937951Z
jonasbn/github-action-spellcheck:0.19.0 2022-01-24T17:19:15.623017Z
jonasbn/github-action-spellcheck:0.18.0 2021-12-18T19:03:53.941591Z
jonasbn/github-action-spellcheck:0.16.0 2021-10-14T19:05:33.111348Z

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

• Я хочу, чтобы пользователи переходили на более новые и современные версии, поскольку они содержат больше исправлений и в целом более стабильны.
• Я не хочу поддерживать старые версии, если кто-то сообщает об ошибке, и она не может быть воспроизведена, или не кажется актуальной в последней версии, обновление будет рекомендовано в качестве средства исправления.
• Документация следует за последней версией, поэтому пользователь может быть заинтересован в том, чтобы быть на последней версии, с наиболее полной, правильной и точной документацией.

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

Таким образом, политика заката должна действовать в рамках, описанных выше.

Жизненный цикл действия можно разделить на две части:

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

Эти два состояния отличаются не так уж сильно, но это стоит принять во внимание.

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

В настоящее время пользователи точно определяют версии. Для того, чтобы они были доступны в течение соответствующего периода времени, предлагается, чтобы релизы были доступны в течение 365 дней (год), что даст пользователям год для обновления до более новой версии.

name: Spellcheck Action
on: push

jobs:
  build:
    name: Spellcheck
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master
    - uses: rojopolis/spellcheck-github-actions@0.23.2
      name: Spellcheck

Пример взят из репозитория til

Просмотр использования на DockerHub показывает, что предложенные 365 дней, похоже, хорошо подходят для использования.

В настоящее время основное внимание уделяется бета-версиям, где релизы могут быть частыми, нерегулярными и непредсказуемыми. Во время бета-версии идея состоит в том, чтобы каждый релиз существовал 365 дней (год), независимо от того, сколько релизов было выпущено.

Когда бета-версия закончится, ожидается, что график выпуска и политика заката изменятся. Ожидается, что релизы станут менее частыми, а требование доступности будет указывать на то, что релиз будет существовать более 365 дней. Объявление о выпуске должно сообщать о сроках доступности более ранних релизов. При необходимости и для поддержки пользователей основные релизы могут быть доступны и дольше, даже если обратная совместимость не может быть обеспечена.

На рисунке показано, что все образы Docker до версии 0.13.0 должны быть удалены из репозитория образов Docker на DockerHub, что и было сделано. Версии 0.13.0 и 0.14.0 уже прошли дату выхода, поэтому в какой-то момент они будут удалены. Как вы можете видеть, оба релиза были недавно использованы, что означает, что репозитории GitHub, предположительно, все еще указывают именно на эти релизы, и PR для подталкивания может быть необходим. Проблема с 0.13.0 не так велика, в то время как прекращение использования версии 0.14.0 требует больше работы, поскольку влияние будет выше.

Введение канонических версий

Предложение по тегам релизов может заключаться в введении канонических версий, так что для бета-версии (0.X.X) каноническая версия будет называться: v0, а для основного релиза, например 1.0.0, канонической версией будет: v1.

Этот тег будет действовать как latest, который указывает на самый новый образ, который также ссылается на последнюю точную версию, например 0.2.3. Эти версии не будут объявлены на GitHub Marketplace, поскольку они являются косвенными и поэтому не будут подхвачены Dependabot или Renovate, или, по крайней мере, мы не заинтересованы в том, чтобы они были подхвачены.

Однако с каноническими версиями есть следующие проблемы:

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

Одной из целей таких инструментов, как Renovate и Dependabot, является предотвращение атак на цепочку инструментов.

В связи с этим возникает несколько проблем:

• Доверяют ли пользователи канонических версий сопровождающим действия?
• Может ли действие сделать что-то вредоносное?

Действие — это репозиторий, как и любой другой, на него тоже можно нацелиться, в настоящее время действие просто загружает репозиторий, анализирует его и сообщает пользователю. Может ли оно быть заменено на что-то, делающее что-то непреднамеренное/вредоносное — да, возможно.

Даже для своих собственных репозиториев я просматриваю все PR, даже от Dependabot и Renovate, и я не уверен, что канонические версии — это хорошая идея.

Я надеюсь, что со стабильным релизом частота релизов снизится, а значит, необходимость в схеме релизов, полагающейся на канонические версии, отпадет.

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

Предложение по политике заката

Вот основная политика заката

• Точные версии (X.X.X) доступны в течение 365 дней.
• Канонические версии (vX) будут доступны вечно

Точные версии во время бета-тестирования (0.X.X) будут доступны в течение 365 дней. Когда будет создана первая стабильная версия (1.0.0), временные рамки в 365 дней могут быть пересмотрены, в зависимости от циклов выпуска.

• Каноническая версия v0, всегда будет указывать на последний бета-релиз (0.X.X).
• Каноническая версия v1, всегда будет указывать на последний выпуск в серии 1.X.X.

Ожидается, что канонические версии (vX) будут доступны всегда. Если и когда несколько основных версий станут доступны (X.0.0), они могут быть объявлены как EOL.

• Точные версии доступны через GitHub marketplace, а обновления могут осуществляться напрямую через Dependabot, Renovate или вручную.
• Канонические версии не выставляются на GitHub Marketplace, и их поддержка будет осуществляться косвенно и автоматически.

Это политика, которую я буду оценивать для использования для «GitHub Spellcheck Action», политика может быть изменена, если это будет сочтено необходимым. Особенно использование канонических версий будет тщательно изучено. Так что, пожалуйста, рассматривайте это как экспериментальное, а предложение — как предложение.