Участие в документации Kubernetes

Edit This Page

Участие в SIG Docs

SIG Docs — это одна из специальных групп в проекте Kubernetes, которая занимается написанием, обновлением и поддержкой документации Kubernetes в целом. Перейдите на страницу про SIG Docs в GitHub-репозитории, чтобы узнать подробную информацию об этой группе.

SIG Docs активно принимает правки и дополнения в документацию, так и отзывы от всех участников. Любой может открыть пулреквест (PR), либо сообщить про ошибки в тексте или просто прокомментировать выполняемые пулреквесты.

Вы также можете стать членом, рецензентом или утверждающим. Эти роли расширяют ваши возможности, но и предлагают выполнение определенных обязанностей по рассмотрению и принятию изменений. Изучите содержимого файла community-membership в директории сообщества репозитория, чтобы узнать про членство в сообществе Kubernetes. В остальной части этой страницы кратко рассматривается функционирование ролей в группе SIG Docs, которая в совокупности отвечает за поддержание одного из самой публичной части Kubernetes — сайта и документации Kubernetes.

Роли и обязанности

  • Любой может поучаствовать в документацию Kubernetes. Для этого вам нужно только подписать CLA и иметь аккаунт на GitHub.
  • Члены организации Kubernetes — участники, которые активно занимаются пректом Kubernetes, как правило, открывая пулреквесты с принятыми изменениями. Посмотрите файл Членство в сообществе, чтобы узнать про необходимые условия для членства.
  • Рецензент SIG Docs — член организации Kubernetes, который занимается проверкой пулреквестов и поэтому был добавлен в соответствующую группу на GitHub и в файлы OWNERS в GitHub-репозитории.
  • Утверждающий SIG Docs — член организации с хорошей репутацией, который подтвердил неизменную приверженность проекту. Утверждающий может принимать пулреквесты и публиковаться от имени организации Kubernetes. Утверждающие также могут представлять группу SIG Docs в более крупном сообществе Kubernetes. Некоторые из задач утверждающего SIG Docs, например, координация новой версии, требуют значительных затрат по времени.

Любой

Кто угодно может сделать следующее:

  • Открыть ишью на GitHub в любую часть Kubernetes, включая документацию.
  • Дать рекомендацию или предложить улучшение в пулреквесте.
  • Предложить идею по улучшению в Slack](http://slack.k8s.io/) или в список рассылки SIG Docs.
  • Использовать команду /lgtm (сокращение от “looks good to me”) бота Prow, чтобы одобрить изменения в пулреквесте.
    Заметка: Если вы не входите в организацию Kubernetes, то команда /lgtm не проставил автоматически соответствующую метку.

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

Члены

Члены — это участники проекта Kubernetes, которые удовлетворяют критериям членства. SIG Docs ценит участие всех членов сообщества Kubernetes и часто просит дать обратную связь от членов других SIG-групп для соблюдения технической точности.

Любой член организации Kubernetes может сделать следующее:

  • Всё то же самое, что и любой другой участник
  • Использовать команду /lgtm в комментарии для автоматического добавления метки LGTM (looks good to me) для пулреквеста.
  • Использовать команду /hold в комментарии для блокировки слияния пулреквеста, если он имеет метку LGTM и другие утверждающие метки.
  • Использовать команду /assign в комментарии, чтобы назначить рецензента, который будет проверят пулреквест.

Членство

После того, как вы успешно отправили не менее 5 содержательных пулреквестов, вы можете стать членом организации Kubernetes. Следуйте нижеперечисленным шагам:

  1. Найдите двух рецензентов или утверждающих, которые поддержат ваше членство.

    Запросите спонсорство в канале #sig-docs Kubernetes Slack или в списке рассылки SIG Docs.

    Заметка: Не отправляйте электронное письмо и не пишите личное сообщение в Slack кому-либо из участников SIG Docs.

  2. Создайте ишью в репозитории kubernetes/org, чтобы запросить членство. Заполните шаблон, предварительно изучив правила членства в сообществе.

  3. Сообщите вашим спонсорам про вашу заявку на GitHub, упомянув их в ней на GitHub (добавив комментарий в форме @<GitHub-username>), либо отправив им ссылку напрямую, чтобы они могли добавить проголосовать ( +1).

  4. Когда ваше членство будет одобрено, член административной команды на GitHub, назначенный для обработки вашего пулреквеста, обновит ишью на GitHub, чтобы показать одобрение, а затем закроет проблему GitHub. Поздравляем, теперь вы член организации!

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

Рецензенты

Рецензенты — это члены GitHub-группы @kubernetes/sig-docs-pr-reviews. Рецензенты проверяют пулреквесты документации и оставлять обратную связь по предлагаемым изменениях. Рецензенты могут:

  • Делать всё то, что и любой участник и члены
  • Писать документацию для новой функциональности
  • Назначать метки и классифицировать ишью
  • Проверять пулреквесты и оставлять обязательные для выполнения рекомендации
  • Создавайте диаграммы, графику и встраиваемые скринкасты и видеоролики
  • Заниматься локализацией
  • Редактировать строки в коде, относящиеся к интерфейсу пользователя
  • Улучшать комментарии к коду

Выбор рецензентов для проверки пулреквестов

Процесс выбора рецензентов для проверки пулреквестов автоматизирован. Вы можете попросить проверку у определенного рецензента, написав комментарий в пулреквесте: /assign [@_github_handle]. Чтобы показать, что пулреквест является правильным с технической точки зрения и не требует дополнительных изменений, рецензент добавляет комментарий с командой /lgtm.

Если назначенный рецензент еще не просмотрел содержимое пулреквеста, может присоединиться другой проверяющий. Кроме того, вы можете назначить технических рецензентов и подождать их одобрение через комментарий с /lgtm.

Также для совсем небольшого изменения, или такого, которое не требует технического рассмотрения, утверждающие SIG Docs одобрить его через комментарий с /lgtm.

Комментарий с /approve от рецензента игнорируется ботом и поэтому соответствующая метка не добавится к пулреквесту.

Как стать рецензентом

Если вы соответствуете требованием, то можете стать рецензентом SIG Docs. Рецензенты в других SIG-группах должны подать новую заявку для получения статуса рецензента в SIG Docs.

Для отправки заявки откройте пулреквест с добавлением самого себя в секцию reviewers корневого файла OWNERS в репозитории kubernetes/website. Запросите проверку вашего пулреквеста одному или нескольким текущим утверждающим в группе SIG Docs.

Если ваш пулреквест одобрен, вы становитесь рецензентом SIG Docs. Теперь бот K8s-ci-robot будет назначать и предлагать вас в качестве рецензента для проверки новых пулреквестов.

После того, как ваша кандидатура будет одобрена, попросите текущего утверждающего SIG Docs добавить вас в GitHub-группу @kubernetes/sig-docs-pr-reviews. Только члены GitHub-группы kubernetes-website-admins могут добавлять новых членов в какую-либо другую группу.

Утверждающие

Утверждающие — члены GitHub-группы @kubernetes/sig-docs-maintainers. Перейдите в раздел Команды и группы в SIG Docs для получения дополнительной информации.

Утверждающие могут делать следующее:

  • Все то же, что и обычные участники, члены и рецензенты
  • Публиковать изменения от других участников путём одобрения и слияния пулреквестов с помощью комментария с командой /approve. Если кто-то оставляет комментарий, не являясь при этом официальным рецензентом, бот проигнорирует такой одобряющий комментарий.
  • Примите участие в работе команды выпуска новых версий Kubernetes как представитель документации
  • Предлагать улучшения в руководстве по оформлению
  • Предлагать улучшения для тестов документации
  • Предлагать улучшения для сайта Kubernetes или других инструментов

Если у PR есть метка /lgtm, или если утверждающий оставляет комментарий с командной с /lgtm, PR автоматически сливается. Утверждающий SIG Docs должен оставлять комментарий с /lgtm только для тех изменений, которые не нуждаются в дополнительном техническом обзоре.

Как стать утверждающим

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

Для отправки заявки откройте пулреквест с добавлением самого себя в секцию approvers корневого файла OWNERS в репозитории kubernetes/website. Запросите проверку вашего пулреквеста одному или нескольким текущим утверждающим в группе SIG Docs.

Если ваш пулреквест одобрен, вы становитесь утверждающим SIG Docs. Теперь бот K8s-ci-robot будет назначать и предлагать вас в качестве рецензента для проверки новых пулреквестов.

После того, как ваша кандидатура будет одобрена, попросите текущего утверждающего SIG Docs добавить вас в GitHub-группу@kubernetes/sig-docs-maintainers. Только члены GitHub-группы kubernetes-website-admins могут добавлять новых членов в какую-либо другую группу.

Обязанности утверждающего

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

  • Утверждающие могут использовать команду /approve, которая сливает PR в репозиторий.

    Невнимательное слияние может нарушить работу сайта, поэтому имейте это в виду, когда объединяете какой-либо пулреквест.

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

    Если вы сомневаетесь или вы не уверены в чем-либо, не стесняйтесь обращаться для дополнительной проверки.

  • Проверьте, что тесты на Netlify пройдены успешно, перед тем как написать комментарий с /approve в PR.

    Netlify tests must pass before approving

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

  • Участвуйте в графике дежурства смотрителя PR, чтобы вас назначили дежурным проверяющим на неделю. SIG Docs ожидает, что все утверждающие примут участие в этом графике. За подробностям обратитесь к странице Be the PR Wrangler for a week.

Председатель SIG Docs

Каждая SIG-группа, включая SIG Docs, выбирает одного или нескольких членов из своей SIG-группы в качестве председателей. Это координаторы между SIG Docs и другими подразделениями в организации Kubernetes. От таких людей требуются обширные знания о структуре проекта Kubernetes в целом и как функционирует группа SIG Docs внутри неё. Смотрите раздел Руководство, чтобы узнать текущий список председателей.

Команды SIG Docs и автоматизация

Автоматизация в SIG Docs основывается на двух разных механизмах: группы GitHub и файлы OWNERS.

GitHub-группы

Группа SIG Docs представлена двумя командами на GitHub:

На каждую из них можно сослаться по имени (@name) в комментариях на GitHub, чтобы общаться со всеми участниками в этой группе.

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

Файлы OWNERS и вступительная часть

Проект Kubernetes использует инструмент автоматизации под названием prow, чтобы автоматизировать процесс, связанный с ишью и пулреквестами на GitHub. Репозиторий сайта Kubernetes использует два плагина prow:

  • blunderbuss
  • approve

Все эти плагины используют файлы OWNERS и OWNERS_ALIASES в корневой директории GitHub-репозитория kubernetes/website, чтобы контролировать работу prow по всему репозиторию.

Файл OWNERS содержит список людей, которые являются рецензентами и утверждающими в SIG Docs. Файлы OWNERS также может быть в поддиректориях и могут переопределять тех, кто может выступать в качестве рецензента или утверждающего в изменениях файлов этой директории и её поддиректорий. Для получения дополнительной информации о файлах OWNERS в целом, перейдите в OWNERS.

Кроме того, в каждом Markdown-файле могут быть указаны рецензенты и утверждающие в так называемой вступительной части (front-matter) в виде логинов участников или имён групп на GitHub.

Таким образом файлы OWNERS и вступительная часть в Markdown-файлах определяет своего рода рекомендацию для бота, чтобы он знал, к кому обращаться за технической и редакционной проверкой каждого PR.

Как происходит слияние

Когда пулреквест сливается в действующую ветку сайта (в данный момент это master), содержимое публикуется и становится общедоступным. Для обеспечения высокого качества публикуемого нами контента, мы доверяем слияние пулреквестов утверждающим SIG Docs. Ниже описан этот процесс.

  • Когда пулреквест имеет метки lgtm и approve, при этом у него нет метки hold, и то же время все тесты успешно проходят, то пулреквест автоматически сливается.
  • Члены организации Kubernetes и утверждающие SIG Docs могут оставлять комментарии со специальными командами, которые блокирует автоматическое объединение пулреквеста (добавление комментарий с текстом /hold или удаление ранее установленной метки /lgtm).
  • Любой участник Kubernetes может добавить метку lgtm, добавив комментарий, включающий в себя /lgtm.
  • Только утверждающие SIG Docs могут слить пулреквест путём добавления комментария с /approve. Некоторые утверждающие также играют дополнительные роли, например, дежурного по PR или председателя SIG Docs.

Что дальше

Для получения дополнительной информации про участие в документации Kubernetes, посмотрите следующие страницы:

Обратная связь