W LinuxДокументация

Участие в W Linux

Спасибо, что заглянули. Баг-репорты, вопросы и патчи — всё приветствуется.

Прежде всего одна особенность этого репозитория, непривычная и стоящая двух минут вашего времени, потому что она меняет судьбу вашего pull request'а.

Как публикуется этот репозиторий

W разрабатывается в приватном репозитории и публикуется здесь серией релизных снапшотов. Каждый коммит в main — это один релиз: полное, протестированное дерево с тегом vX.Y.Z и списком изменений в сообщении коммита. Повседневной истории коммитов здесь нет и не будет.

Два следствия:

Эта ветка только дополняется. Установленные машины с W следуют за ней через git pull --ff-only. Переписанная или форс-запушенная история оставила бы за бортом каждую из них, поэтому такого не происходит.

Pull request'ы приземляются руками, а не кнопкой «merge». Слияние PR здесь положило бы в ветку не-релизный коммит и сломало бы описанную выше модель. Вместо этого ваш патч применяется к дереву разработки, там ревьюится и тестируется и приезжает в следующем релизе. Когда этот релиз выходит, ваш PR закрывается со ссылкой на него — закрывается, а не отклоняется. Ваше авторство сохраняется через Co-authored-by, и вы упоминаетесь в release notes.

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

Как сообщить о баге

Откройте issue. Что действительно помогает:

  • Строки IMAGE_VERSION и W_BUILD_DATE из /etc/os-release
  • w-sync status — на каком канале и ref'е находится машина
  • Относящийся к делу лог. W логирует собственную работу в /var/log/w/; sudo /var/lib/w/src/scripts/collect-logs.sh собирает полный диагностический комплект, если вы хотите его приложить. Прочитайте его перед тем, как прикладывать, — это системная диагностика, и в ней могут оказаться имена хостов, пользователей, сетей или пути, которые вы предпочли бы не публиковать.
  • Железо, когда баг выглядит железозависимым (GPU, модель ноутбука, конфигурация мониторов)

По всему, что чувствительно с точки зрения безопасности, issue не открывайте — см. SECURITY.md.

Как прислать патч

  1. Сделайте форк, ветку и правку относительно main.

  2. Прогоните проверки. scripts/check.sh — статический гейт проекта: линтеры shell и Python, инварианты прав и манифестов, маршрутизация доставки, слоёный конфиг, i18n, линт QML и юнит-тесты. Это занимает секунды и обязано быть зелёным:

    ./scripts/check.sh              # всё
./scripts/check.sh --bash       # один сьют

    Отсутствующие линтеры пропускают свой сьют с предупреждением, а не роняют прогон, так что и с неполным набором инструментов вы пройдёте бо́льшую часть пути.

  3. Если правка затрагивает что-либо видимое пользователю, расскажите, как вы проверили это на настоящей машине или в VM. В vm/ лежит собственный стенд проекта: vm/start.sh поднимает dev-VM, vm/e2e.sh прогоняет установку без участия человека от начала до конца.

  4. Откройте PR. Объясните, что ломается без вашей правки, — это полезнее, чем пересказ диффа.

Как должен выглядеть код

Так же, как то, что уже есть. Конкретно:

  • Shell — это bash с set -euo pipefail, чистый по shellcheck. Python — чистый по ruff. И то, и другое проверяется check.sh.
  • Комментарии объясняют «почему», а не «что». Существующий код тяжело нагружен обоснованиями — в какую ловушку наступили, какую альтернативу отвергли и по какой причине. Это сделано намеренно; продолжайте в том же духе. Комментарий, пересказывающий строку под собой, — шум.
  • Уважайте границу владения. Файлы, которыми управляет W, перезаписываются при каждом обновлении; файлы, которыми владеет пользователь, засеваются один раз и больше не трогаются. Что к чему относится — объявлено в манифестах модулей под rootfs/usr/share/w/update/*.manifest, и check.sh это проверяет. Добавляете поставляемый файл — добавьте строку в манифест в той же правке.
  • Новый модуль — новая маршрутизация. rootfs/usr/share/w/update/sync-map решает, какой модуль apply.sh запускается при изменении данного пути. Сьют routing падает, если поставляемому файлу некуда идти.
  • Держите дифф в рамках задачи. Попутное переформатирование нетронутого кода усложняет ревью, и его обычно попросят убрать.

О чём стоит спросить заранее

Откройте issue до начала работы, если ваша правка добавляет зависимость, новую директорию верхнего уровня, новый инструмент w-* или меняет поток шагов инсталлятора. Это архитектурные вещи, и обсудить их дешевле, чем переделать.

Лицензия

Внося вклад, вы соглашаетесь, что ваша работа лицензируется под GPL-3.0-or-later — лицензией этого проекта, — а вносимая вами графика лицензируется под CC BY-SA 4.0; это разделение описано в COPYING.assets. CLA нет, передачи авторских прав нет; вы сохраняете своё авторское право.

Изменить эту страницу на GitHub